@nitra/cursor 12.15.1 → 12.16.1

package/scripts/lib/fix/docs/orchestrator.md

@@ -3,38 +3,31 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: c6f15470
+  crc: 49146418
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль відповідає за оркестрацію вирішення порушень. Він парсить аргументи для визначення бюджету та фільтрів за допомогою `parseOrchestratorArgs`. Потім він будує послідовність тирів ескалації, використовуючи `buildLadder`, і може ескалувати правила за допомогою `escalateRule`. Нарешті, він виконує повний цикл фіксації порушень через `runOrchestratorCli`.
+Цей модуль керує процесом виправлення порушень. Він виконує функцію `parseOrchestratorArgs` для визначення обсягу роботи з хмарними моделями та фільтрами правил. Модуль забезпечує класифікацію помилок через `classifyFixError` та ескалацію правил за допомогою `escalateRule`. Крім того, він створює структуру для застосування правил за допомогою `buildLadder` і запускає основний клієнтський процес за допомогою `runOrchestratorCli`.
 
 ## Поведінка
 
-buildLadder будує послідовність тирів ескалації для вирішення порушень, від локальних до хмарних моделей.
-escalateRule проводить один прогін по послідовності тирів, намагаючись вирішити порушення, і повертає статус вирішення та використаний бюджет хмарних викликів.
-parseOrchestratorArgs парсить аргументи командного рядка, щоб визначити максимальний бюджет хмарних викликів та фільтр правил.
-runOrchestratorCli виконує повний цикл фіксації порушень: початкова перевірка, детермінований фікс T0-auto, ітеративний LLM-фікс за драбиною ескалації, а потім фінальна перевірка.
+Поведінка:
+classifyFixError визначає тип помилки, виниклої при спробі виправлення.
+buildLadder конструює послідовність моделей для багаторівневої спроби усунення порушень.
+escalateRule ітерує по моделях драбини, намагаючись виправити одне порушення, і звітує про результат.
+parseOrchestratorArgs виділяє максимальну кількість викликів хмарної моделі та фільтр правил із вхідних аргументів.
+runOrchestratorCli виконує повний цикл фіксації порушень, включаючи початкову перевірку, детерміноване виправлення та ітерації з LLM.
 
 ## Публічний API
 
-buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів.
-
-local-min — Перший прохід з локальною мінімальною моделлю.
-local-min-retry — Повторний прохід локальною моделлю з урахуванням результатів попереднього кроку.
-cloud-min — Використання мінімальної хмарної моделі з зворотним зв'язком.
-cloud-avg — Використання середньої хмарної моделі з зворотним зв'язком, обмежене середнім бюджетом.
-
-escalateRule — Застосовує одне правило по послідовності ескалації до першого успішного перевірки.
-Кожен рунг — Викликає обробника з попереднім результатом, перевіряє правило, фіксує результат у лозі.
-Достроковий вихід — Зупиняє процес при певних умовах (відсутність ключа, пропуск моделі на системному рівні) або перевищенні середнього бюджету.
-
-parseOrchestratorArgs — Витягує максимальне значення середнього бюджету з аргументів командного рядка та збирає фільтри правил.
-
-runOrchestratorCli — Запускає основний процес оркестрації з командного рядка.
+classifyFixError — Визначає тип помилки, яку виявив pi-agent-fix: системна, транспортна чи якісна.
+buildLadder — Створює послідовність моделей для усунення помилок, починаючи з найменш ресурсомістких локальних спроб і рухаючись до хмарних моделей, враховуючи попередній досвід.
+escalateRule — Застосовує одне правило за визначеною драбиною, повторюючи перевірку після кожного кроку та фіксуючи результати у лозі.
+parseOrchestratorArgs — Зчитує аргументи командного рядка, зокрема максимальний бюджет середнього рівня, та витягує фільтр правил.
+runOrchestratorCli — Виконує основну логіку оркестрації, керуючи циклом виявлення, класифікації та ескалації виправлень.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/escalation-log.mjs

@@ -5,7 +5,7 @@
  * правило стало зеленим після цього рунга (`recheckOk` = «чи допомогло»),
  * залишковий violation і `diagnosis` (само-аналіз моделі «чому не вдалося»).
  *
- * Це доповнення до always-on wire-trace (`lib/omlx-trace.mjs`): trace знає
+ * Це доповнення до always-on wire-trace (`lib/pi-trace.mjs`): trace знає
  * `messages`/`reasoning`/`usage` кожного виклику, але **не** знає результату
  * re-check — а саме «чи допомогло» й потрібне для пост-аналізу драбини. Join із
  * trace — за полем `caller` (`fix:<rule>:<rung>`), яке цей модуль і формує.

package/scripts/lib/fix/orchestrator.mjs

@@ -4,10 +4,9 @@ import { env } from 'node:process'
 import { runConformanceCheck } from './run-conformance-check.mjs'
 import { runT0AutoCli } from './t0.mjs'
 import { logEscalation } from './escalation-log.mjs'
-import { runLlmWorker } from './llm-worker.mjs'
-import { printVerboseBlock } from './verbose-block.mjs'
-import { classifyOmlxError } from '../../../lib/llm.mjs'
-import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
+import { runPiAgentFix } from '../../../lib/pi-agent-fix.mjs'
+import { recordFixTelemetry } from '../../../lib/pi-telemetry-store.mjs'
+import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/pi-model-tiers.mjs'
 
 /**
  * Дефолтний кеп на виклики хмарної avg-моделі за один прогін (щоб драбина на N
@@ -16,23 +15,41 @@ import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
 const DEFAULT_MAX_AVG = 3
 
 /**
- * Timeout одного LLM-виклику (або всієї агентної сесії) за тиром.
- * Локальні рунги — 5 хвилин: 4b модель повільна, основний backstop — turn-ceiling (~50).
- * Хмарні — 2 хвилини: API-виклик швидкий, перевищення = transport-помилка.
+ * Timeout усієї агентної сесії за тиром. Агентний фікс — багатоходовий
+ * (read→edit→self_check, кожен turn = окремий API-раунд), тож на правилах із багатьма
+ * порушеннями навіть швидкий cloud не вкладається у пару хвилин (вимір: gpt-5.4-mini
+ * timeout на test/doc-files/npm-module за 120s). Тому cloud — теж 5 хв, як local;
+ * основний backstop усе одно turn-ceiling (~50) у pi-agent-fix.
  * Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
  */
 const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 300_000
-const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
+const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 300_000
 
-/** Маркер дружнього повідомлення про відсутній API-ключ (з `llm-worker.callModel`). */
-const NO_KEY_RE = /немає ключа|api key/i
+/** Реальний транспорт-збій провайдера (мережа/сокет) — НЕ наш агентний backstop-timeout. */
+const TRANSPORT_RE = /etimedout|timed out|econnrefused|connection refused/i
 
 /**
- * Хмарний транспорт (pi) упав на рівні процесу: таймаут/spawn-помилка. Стіна часу
- * однакова для всіх cloud-рунгів (та сама pi-транспортна стіна), а cloud-avg — інша
- * модель, не більший timeout. Ескалація на неї лише спалить avg-бюджет → обрив.
+ * Systemic — повтор тієї ж моделі марний: нема git, fail-closed guard, відсутня модель,
+ * registry/session/auth. Quality — модель видала поганий фікс (retry/escalate може допомогти).
  */
-const CLOUD_TRANSPORT_RE = /etimedout|timed out|pi error/i
+const SYSTEMIC_RE = /не git-репо|fail-closed|write-guard|модель не знайдена|registry:|session:|немає ключа|api key/i
+
+/**
+ * Класифікує помилку pi-agent-fix: systemic | transport | quality (замінює
+ * `classifyOmlxError` після pi-міграції — помилки приходять як винятки з `session.prompt`).
+ * @param {string|null|undefined} error повідомлення помилки
+ * @returns {'systemic'|'transport'|'quality'|null} клас
+ */
+export function classifyFixError(error) {
+  if (!error) return null
+  // Наш агентний backstop-timeout — НЕ транспорт-збій провайдера: модель працювала, просто
+  // не встигла. Тому quality (а не transport-break) → драбина падає на наступний (сильніший)
+  // rung, замість обриву; для cloud-min це означає шанс cloud-avg.
+  if (/^fix timeout /i.test(error)) return 'quality'
+  if (SYSTEMIC_RE.test(error)) return 'systemic'
+  if (TRANSPORT_RE.test(error)) return 'transport'
+  return 'quality'
+}
 
 /**
  * Будує драбину ескалації за наявними тирами (спека 2026-06-19-fix-escalation-cascade):
@@ -73,9 +90,9 @@ export function buildLadder({ localMin, cloudMin, cloudAvg }) {
  */
 function decideAfterFailure(rung, error) {
   if (!error) return null
-  if (NO_KEY_RE.test(error)) return 'break'
-  if (rung.local && classifyOmlxError(error) === 'systemic') return 'skip-model'
-  if (!rung.local && CLOUD_TRANSPORT_RE.test(error)) return 'break'
+  const kind = classifyFixError(error)
+  if (kind === 'systemic') return rung.local ? 'skip-model' : 'break'
+  if (!rung.local && kind === 'transport') return 'break'
   return null
 }
 
@@ -88,7 +105,7 @@ function decideAfterFailure(rung, error) {
  * @param {string} cwd корінь проєкту
  * @param {{
  *   ladder: Array<{tier:string,model:string,feedback:boolean,local:boolean,isAvg:boolean}>,
- *   worker: { runLlmWorker: (ruleId: string, violation: string, cwd: string, opts: object) => object },
+ *   worker: { runFix: (ruleId: string, violation: string, cwd: string, opts: object) => Promise<object> },
  *   check: (rules: string[], cwd: string) => Promise<{rules: Array<{ruleId:string,ok:boolean,output:string}>}>,
  *   avgBudget: number,
  *   clock?: () => number,
@@ -126,42 +143,59 @@ export async function escalateRule(rule, cwd, deps) {
     }
 
     const startedAt = clock()
-    const res = worker.runLlmWorker(rule.ruleId, currentViolation, cwd, {
+    // self_check (advisory §4+5) — той самий verdict-helper, що й зовнішній re-check.
+    const selfCheck = async () => {
+      const r = await check([rule.ruleId], cwd)
+      return { ok: r.rules.every(x => x.ok), output: r.rules.find(x => !x.ok)?.output ?? 'ok' }
+    }
+    const res = await worker.runFix(rule.ruleId, currentViolation, cwd, {
       model: rung.model,
+      tier: rung.tier,
       feedback: rung.feedback ? feedback : null,
       caller: `fix:${rule.ruleId}:${rung.tier}`,
-      timeoutMs: rung.timeoutMs
+      timeoutMs: rung.timeoutMs,
+      deps: { selfCheck }
     })
     if (rung.isAvg) avgUsed++
 
+    // Зовнішній canonical re-check = джерело правди (§4+5).
     const recheck = await check([rule.ruleId], cwd)
     const recheckOk = recheck.rules.every(r => r.ok)
     const remaining = recheckOk ? '' : (recheck.rules.find(r => !r.ok)?.output ?? '')
+
+    // Distillation-стор §13: persist кожну спробу (повні edits + verdict).
+    if (res.telemetry) {
+      recordFixTelemetry({
+        ...res.telemetry,
+        violationSignature: currentViolation,
+        recheck: { external: recheckOk ? 'pass' : 'fail' },
+        escalated: !recheckOk
+      })
+    }
+
     record({
       ...common,
-      callOk: res.ok,
+      callOk: !res.error,
       callError: res.error ?? null,
       recheckOk,
       remainingViolation: remaining,
-      diagnosis: res.diagnosis ?? null,
+      diagnosis: res.telemetry ? `turns=${res.telemetry.turnCount} tools=${res.telemetry.toolCallCount}` : null,
       ms: clock() - startedAt
     })
 
     if (recheckOk) {
       log(`  ✅ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}`)
-    } else {
-      const hint = res.error ? ` ❌ ${res.error.slice(0, 120)}` : ' ❌ досі порушено'
-      log(`  ⚡ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}${hint}`)
+      return { resolved: true, avgUsed }
     }
 
-    if (env.N_CURSOR_FIX_VERBOSE !== 'off' && res.promptSummary) {
-      printVerboseBlock(rule.ruleId, res.promptSummary, res.reasoning ?? null, res.reasoningSource ?? null)
-    }
+    const hint = res.error ? ` ❌ ${res.error.slice(0, 120)}` : ' ❌ досі порушено'
+    log(`  ⚡ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}${hint}`)
 
-    if (recheckOk) return { resolved: true, avgUsed }
+    // Recheck провалився → clean-slate per rung: відкотити правки цього рунга (§12).
+    res.rollback?.()
 
     // Feedback для наступного рунга + оновлений violation.
-    feedback = { previousModel: rung.model, previousChanges: res.changes ?? [], previousError: res.error ?? null }
+    feedback = { previousModel: rung.model, previousError: res.error ?? null }
     currentViolation = remaining || currentViolation
 
     const action = decideAfterFailure(rung, res.error)
@@ -211,7 +245,7 @@ async function runT0Step(cwd, ruleFilter, failed) {
  * @returns {Promise<number>}  0 = all clean, 1 = unresolved
  */
 export async function runOrchestratorCli(args, cwd) {
-  const worker = { runLlmWorker }
+  const worker = { runFix: runPiAgentFix }
   const { maxAvg, ruleFilter } = parseOrchestratorArgs(args)
   const ladder = buildLadder({ localMin: LOCAL_MIN, cloudMin: CLOUD_MIN, cloudAvg: CLOUD_AVG })
 

package/scripts/lib/skill-meta.mjs

@@ -19,6 +19,15 @@ import { join } from 'node:path'
 /** Літерал безумовної автоактивації (українською, як у `auto-skills.mjs`). */
 export const SKILL_ALWAYS = 'завжди'
 
+/** Допустимі тири моделі для агентного виконання скіла (`pi`-runner). */
+export const SKILL_TIERS = ['min', 'avg', 'max']
+
+/**
+ * Дефолтна тира за відсутності `main.json.tier`: скіли відкриті й агентні, слабка
+ * локальна модель іде в мета-рамблінг, тож безпечніше дефолтити в найсильніший тир.
+ */
+export const DEFAULT_SKILL_TIER = 'max'
+
 /**
  * @typedef {{ always: true } | { rules: string[] }} SkillAutoSpec
  */
@@ -50,6 +59,19 @@ export function skillRequiresRoot(meta) {
   return meta?.worktree === true || meta?.requireRoot === true
 }
 
+/**
+ * Тира моделі для агентного виконання скіла (`pi`-runner). Повертає `main.json.tier`,
+ * якщо це валідний тир, інакше — `DEFAULT_SKILL_TIER` (`max`).
+ * @param {Record<string, unknown> | null} meta розпарсений `main.json` (або null)
+ * @returns {'min'|'avg'|'max'} тира
+ */
+export function skillTier(meta) {
+  const tier = meta?.tier
+  return typeof tier === 'string' && SKILL_TIERS.includes(tier)
+    ? /** @type {'min'|'avg'|'max'} */ (tier)
+    : DEFAULT_SKILL_TIER
+}
+
 /**
  * Читає й парсить `main.json` одного скіла.
  * @param {string} skillDir абсолютний шлях до каталогу скіла

package/scripts/skills-cli.mjs

@@ -3,14 +3,16 @@
  *
  * Скіли читаються з `npm/skills/<id>/SKILL.md` установленого пакета (або кешу `npx`).
  * Промпт збирає інструкцію скілу + контекст поточного CWD (`package.json`, `tsconfig.json`,
- * `.n-cursor.json`) — далі stdout або делегування в `cursor-agent` / `claude`.
+ * `.n-cursor.json`) — далі stdout або виконання через вбудований pi-агент
+ * (рекомендовано), чи deprecated-делегування в `cursor-agent` / `claude`.
  *
  * Підтримувані формати:
  *   `npx \@nitra/cursor skill list`
  *   `npx \@nitra/cursor skill taze`
- *   `npx \@nitra/cursor skill cursor taze`
- *   `npx \@nitra/cursor skill cursor taze "онови залежності"`
- *   `npx \@nitra/cursor skill claude taze` — те саме через Claude Code CLI
+ *   `npx \@nitra/cursor skill pi taze` — виконати через вбудований pi-агент (рекомендовано)
+ *   `npx \@nitra/cursor skill pi taze "онови залежності"`
+ *   `npx \@nitra/cursor skill cursor taze` — deprecated: зовнішній Cursor CLI
+ *   `npx \@nitra/cursor skill claude taze` — deprecated: зовнішній Claude Code CLI
  */
 
 import { spawnSync } from 'node:child_process'
@@ -19,14 +21,18 @@ import { dirname, join } from 'node:path'
 import { cwd } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
-const RUNNERS = new Set(['cursor', 'claude'])
+import { readSkillMetaRaw, skillTier } from './lib/skill-meta.mjs'
+
+/** Виконавці скіла. `pi` — вбудований (рекомендований); `cursor`/`claude` — deprecated зовнішні CLI. */
+const RUNNERS = new Set(['pi', 'cursor', 'claude'])
 
 const USAGE_LINES = [
   'Usage:',
   '  npx @nitra/cursor skill list',
   '  npx @nitra/cursor skill <skill-id> ["task"]',
-  '  npx @nitra/cursor skill cursor <skill-id> ["task"]',
-  '  npx @nitra/cursor skill claude <skill-id> ["task"]',
+  '  npx @nitra/cursor skill pi <skill-id> ["task"]      # вбудований pi-агент (рекомендовано)',
+  '  npx @nitra/cursor skill cursor <skill-id> ["task"]  # deprecated',
+  '  npx @nitra/cursor skill claude <skill-id> ["task"]  # deprecated',
   '',
   'Skill id: каталог у пакеті (lint, taze, …) або з префіксом n- (n-lint → lint).'
 ]
@@ -124,15 +130,43 @@ export function buildSkillPrompt(skillsRoot, rawSkillName, task, projectDir = cw
 }
 
 /**
+ * Виконує скіл через вбудований pi-агент (рекомендований шлях). Модель — з тиру скіла
+ * (`main.json.tier`, дефолт `max`); `cwd` = каталог виклику (worktree, за потреби,
+ * створює сам скіл за SKILL.md-preflight). Pi вантажиться lazy.
+ * @param {string} prompt готовий `buildSkillPrompt`
+ * @param {string} rawSkillName ім'я скілу з CLI (можливо з префіксом n-)
+ * @param {string} skillsRoot абсолютний шлях до `skills/` пакета
+ * @param {string} projectDir робочий каталог сесії (= каталог виклику)
+ * @param {(line: string) => void} logError вивід помилок
+ * @param {{ runPiAgentSkill?: Function }} deps інжекти для тестів
+ * @returns {Promise<number>} exit code (0 — ok)
+ */
+async function runPiRunner(prompt, rawSkillName, skillsRoot, projectDir, logError, deps = {}) {
+  const skillId = normalizeSkillId(rawSkillName)
+  const tier = skillTier(readSkillMetaRaw(join(skillsRoot, skillId)))
+  const runPiAgentSkill = deps.runPiAgentSkill ?? (await import('../lib/pi-agent-skill.mjs')).runPiAgentSkill
+  const result = await runPiAgentSkill(prompt, { skillId, tier, cwd: projectDir })
+  if (result.error) {
+    logError(result.error)
+  }
+  return result.ok ? 0 : 1
+}
+
+/**
+ * Deprecated: делегує у зовнішній `claude -p` / `cursor-agent -p`. Лишається як fallback
+ * для тих, у кого pi-модель ще не налаштована; буде прибрано (мігруй на `skill pi`).
  * @param {'claude' | 'cursor'} kind який LLM CLI запускати
  * @param {string} prompt промпт для передачі у stdin
  * @param {string} projectDir робочий каталог дочірнього процесу
+ * @param {(line: string) => void} logError вивід попередження/помилок
  * @returns {number} exit code дочірнього процесу
  */
-function runLlmCli(kind, prompt, projectDir) {
+function runLlmCli(kind, prompt, projectDir, logError) {
+  logError(`[deprecated] skill ${kind} → use 'skill pi'; зовнішній CLI буде прибрано`)
+
   if (kind === 'claude') {
     if (!isBinaryInPath('claude')) {
-      throw new Error('`claude` not found in PATH. Install Claude Code CLI or use `skill cursor`.')
+      throw new Error('`claude` not found in PATH. Install Claude Code CLI or use `skill pi`.')
     }
 
     const result = spawnSync('claude', ['-p'], {
@@ -145,7 +179,7 @@ function runLlmCli(kind, prompt, projectDir) {
   }
 
   if (!isBinaryInPath('cursor-agent')) {
-    throw new Error('`cursor-agent` not found in PATH. Install Cursor CLI or use `skill claude`.')
+    throw new Error('`cursor-agent` not found in PATH. Install Cursor CLI or use `skill pi`.')
   }
 
   const result = spawnSync('cursor-agent', ['-p'], {
@@ -168,15 +202,16 @@ export function resolveBundledPackageRoot(fromModuleUrl = import.meta.url) {
 
 /**
  * @param {string[]} argv аргументи після `skill` у `n-cursor`
- * @param {{ packageRoot?: string, projectDir?: string, log?: (line: string) => void, logError?: (line: string) => void }} [options] перевизначення кореня пакета, каталогу проєкту та функцій виводу (для тестів)
- * @returns {number} exit code
+ * @param {{ packageRoot?: string, projectDir?: string, log?: (line: string) => void, logError?: (line: string) => void, deps?: { runPiAgentSkill?: Function } }} [options] перевизначення кореня пакета, каталогу проєкту, функцій виводу та інжектів (для тестів)
+ * @returns {Promise<number>} exit code
  */
-export function runSkillsCli(argv, options = {}) {
+export async function runSkillsCli(argv, options = {}) {
   const log = options.log ?? (line => console.log(line))
   const logError = options.logError ?? (line => console.error(line))
   const packageRoot = options.packageRoot ?? resolveBundledPackageRoot()
   const skillsRoot = join(packageRoot, 'skills')
   const projectDir = options.projectDir ?? cwd()
+  const deps = options.deps ?? {}
 
   const [first, second, ...rest] = argv
   const skillIds = listSkillIds(skillsRoot)
@@ -201,7 +236,10 @@ export function runSkillsCli(argv, options = {}) {
       }
       const task = rest.join(' ')
       const prompt = buildSkillPrompt(skillsRoot, second, task, projectDir)
-      return runLlmCli(/** @type {'claude' | 'cursor'} */ (first), prompt, projectDir)
+      if (first === 'pi') {
+        return await runPiRunner(prompt, second, skillsRoot, projectDir, logError, deps)
+      }
+      return runLlmCli(/** @type {'claude' | 'cursor'} */ (first), prompt, projectDir, logError)
     }
 
     if (skillIds.includes(normalizeSkillId(first))) {

package/scripts/utils/ast-extract.mjs

@@ -0,0 +1,105 @@
+/** @see ./docs/ast-extract.md */
+
+/**
+ * Generic AST-facts extractor для `ast_facts`-tool fix-engine (§3б спеки pi-migration).
+ *
+ * Дає агенту структурований зріз файлу (`imports` / `exports` / `topLevelFunctions`)
+ * замість сирого вмісту — скорочує redundant read-turns на слабкій локальній моделі.
+ * Використовується як **generic fallback**, коли правило не має власного
+ * `rules/<id>/js/_ast-context.mjs`.
+ *
+ * Парсинг — через спільний `parseProgramOrNull` (oxc). Будь-яка помилка (read/parse)
+ * деградує до `{ error, imports:[], exports:[], topLevelFunctions:[] }`, щоб агент
+ * продовжив із тим, що має (контракт §3б: fallback до голого вмісту).
+ */
+
+import { readFileSync } from 'node:fs'
+import { parseProgramOrNull } from './ast-scan-utils.mjs'
+
+/** Порожній результат із причиною (read/parse fail). @param {string} error причина */
+function empty(error) {
+  return { error, imports: [], exports: [], topLevelFunctions: [] }
+}
+
+/** Чи init-вираз — функція (для `export const f = () => …`). @param {unknown} node init */
+function isFunctionInit(node) {
+  return !!node && (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression')
+}
+
+/**
+ * Витягає AST-факти з вихідного коду (без файлового IO — для тестів і reuse).
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях (визначає мову js/ts/jsx/tsx)
+ * @returns {{ imports: Array<{source: string, names: string[]}>, exports: string[], topLevelFunctions: string[], error?: string }} факти
+ */
+export function extractContextFromSource(content, virtualPath) {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return empty('parse failed')
+
+  const imports = []
+  const exports = []
+  const topLevelFunctions = []
+
+  for (const node of program.body ?? []) {
+    switch (node?.type) {
+      case 'ImportDeclaration':
+        imports.push({
+          source: node.source?.value ?? '',
+          names: (node.specifiers ?? []).map(s => s.local?.name).filter(Boolean)
+        })
+        break
+
+      case 'FunctionDeclaration':
+        if (node.id?.name) topLevelFunctions.push(node.id.name)
+        break
+
+      case 'ExportNamedDeclaration': {
+        const d = node.declaration
+        if (d?.type === 'FunctionDeclaration' && d.id?.name) {
+          exports.push(d.id.name)
+          topLevelFunctions.push(d.id.name)
+        } else if ((d?.type === 'ClassDeclaration' || d?.type === 'TSInterfaceDeclaration') && d.id?.name) {
+          exports.push(d.id.name)
+        } else if (d?.type === 'VariableDeclaration') {
+          for (const decl of d.declarations ?? []) {
+            if (!decl.id?.name) continue
+            exports.push(decl.id.name)
+            if (isFunctionInit(decl.init)) topLevelFunctions.push(decl.id.name)
+          }
+        }
+        for (const spec of node.specifiers ?? []) {
+          if (spec.exported?.name) exports.push(spec.exported.name)
+        }
+        break
+      }
+
+      case 'ExportDefaultDeclaration':
+        exports.push('default')
+        break
+
+      case 'ExportAllDeclaration':
+        exports.push(node.exported?.name ?? '*')
+        break
+
+      default:
+        break
+    }
+  }
+
+  return { imports, exports, topLevelFunctions }
+}
+
+/**
+ * Читає файл і витягає AST-факти. Read-помилка → `{ error, … }` (не кидає).
+ * @param {string} filePath абсолютний/відносний шлях до файлу
+ * @returns {{ imports: Array<{source: string, names: string[]}>, exports: string[], topLevelFunctions: string[], error?: string }} факти
+ */
+export function extractContext(filePath) {
+  let content
+  try {
+    content = readFileSync(filePath, 'utf8')
+  } catch (e) {
+    return empty(`read failed: ${e.message}`)
+  }
+  return extractContextFromSource(content, filePath)
+}

package/scripts/utils/docs/ast-extract.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: ast-extract.mjs
+resource: npm/scripts/utils/ast-extract.mjs
+docgen:
+  crc: 61e8c7bc
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль аналізує вихідний код, витягуючи ключові структурні елементи. Він дозволяє отримати інформацію про імпорти, експорти та назви верхнерівневих функцій, використовуючи функції `f`, `extractContextFromSource` та `extractContext`. Функціонал працює з кодом, наданим безпосередньо або шляхом до файлу. Процес аналізу реалізований з механізмом перехоплення помилок (fail-safe), гарантуючи, що винятки не будуть викинуті назовні.
+
+## Поведінка
+
+f: витягує структурований зріз коду, включаючи імпорти, експорти та назви верхнерівневих функцій.
+extractContextFromSource: витягує структурований зріз коду з наданого вмісту, визначуючи імпорти, експорти та назви верхнерівневих функцій.
+extractContext: читає вміст файлу за вказаним шляхом і витягує з нього структуровані факти коду, обробляючи помилки під час читання.
+
+## Публічний API
+
+- f — основна логіка модуля
+- extractContextFromSource — аналізує структуру коду, наданого як текст, для отримання його граматичного представлення, не звертаючись до файлової системи
+- extractContext — читає вміст файлу та аналізує його структуру, повертаючи помилку читання замість помилки виконання
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/lib/docs/llm.md

@@ -1,33 +0,0 @@
----
-type: JS Module
-title: llm.mjs
-resource: npm/lib/llm.mjs
-docgen:
-  crc: 22d2906f
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
----
-
-Файл є єдиною точкою LLM-викликів для JS-оркестраторів (див. ADR 260610-2228). Він маршрутизує запити виключно за префіксом `model-id` (конвенція `npm/lib/models.mjs`): `omlx/<model>` — прямий HTTP до локального omlx-сервера (`callOmlx`), будь-що інше — через `pi` CLI (хмарні провайдери або pi-дефолт). Рядок моделі сам визначає транспорт; відсутні env-перемикачі бекенду. Кожен виклик має **always-on** багатий JSONL-запис трасування (reasoning + слід). Для `omlx` захоплюються `content/reasoning/usage/finish_reason/attempts`, для `pi` — лише те, що надає CLI (rich-поля null). Код спирається на конфігурації, визначені у settings.json.
-
-## Поведінка
-
-pickBackend визначає, чи має бути використаний локальний omlx-сервер для виклику LLM, чи зовнішній CLI `pi`, на основі префікса `model-id`.
-callLlmRich виконує універсальний виклик LLM з маршрутизацією між omlx та `pi` CLI, завжди записуючи детальний слід (wire-trace) для обох каналів, і повертає вміст та монолог обробки.
-callLlm повертає лише текстовий вміст відповіді від LLM, використовуючи `callLlmRich` як внутрішню обгортку.
-classifyOmlxError класифікує помилку, отриману від omlx-сервера, як тимчасову, системну чи постійну, для прийняття рішення оркестратором.
-omlxHealthCheck виконує мінімальний перевірочний виклик до omlx-сервера для визначення його стану (працює, потребує ключа, перевантажений).
-preflightLocalModel перевіряє стан локальної omlx-моделі, щоб визначити, чи можна безпечно ініціювати виклик, надаючи зрозуміле повідомлення про проблеми з пам'яттю, автентифікацією чи доступністю сервера.
-
-## Публічний API
-
-pickBackend — Визначає, який механізм зв'язку використовувати для моделі: прямий HTTP або CLI.
-callLlmRich — Виконує універсальний запит до LLM, маршрутизуючи його за префіксом моделі та відстежуючи трасування, повертаючи детальний об'єкт з відповіддю та логікою обґрунтування.
-callLlm — Викликає LLM, повертаючи лише текстовий вміст відповіді, зберігаючи сумісність зі старими споживачами.
-classifyOmlxError — Аналізує помилки omlx після вичерпання внутрішніх спроб, щоб визначити, чи потрібно ігнорувати, зупинити роботу (circuit-breaker) чи обробляти як звичайну помилку.
-omlxHealthCheck — Перевіряє готовність omlx-сервера мінімальним запитом, щоб визначити його стан: відсутність відповіді, обмеження пам'яті, відсутність ключа або інша помилка.
-preflightLocalModel — Перевіряє можливість використання локальної моделі для швидкого пропуску викликів, використовуючи файли документації та словники.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/lib/docs/models.md

@@ -1,48 +0,0 @@
----
-type: JS Module
-title: models.mjs
-resource: npm/lib/models.mjs
-docgen:
-  crc: 181e2bf9
-  score: 100
----
-
-Файл визначає глобальну класифікацію моделей для pi. Конфігурація встановлюється через змінні середовища (наприклад, `N_LOCAL_MIN_MODEL`) та використовується для визначення, який провайдер буде викликаний. Кожен скіл посилається на потрібний тир, який використовується для вибору моделі.
-
-## Поведінка
-
-LOCAL_MIN
-Завантажує модель для мінімального локального виведення
-
-LOCAL_AVG
-Завантажує модель для середнього локального виведення
-
-LOCAL_MAX
-Завантажує модель для максимального локального виведення
-
-CLOUD_MIN
-Завантажує модель для мінімального хмарного виведення
-
-CLOUD_AVG
-Завантажує модель для середнього хмарного виведення
-
-CLOUD_MAX
-Завантажує модель для максимального хмарного виведення
-
-resolveModel
-Повертає перший непорожній model-id для запитаного тиру, каскадно перевіряючи локальні тири, а тоді хмарний еквівалент
-
-## Публічний API
-
-LOCAL_MIN — Швидкий локальний inference. Напр.: ollama/gemma3:4b
-LOCAL_AVG — Середній локальний. Напр.: ollama/gemma4:26b-moe
-LOCAL_MAX — Максимальний локальний. Напр.: ollama/llama4-maverick
-CLOUD_MIN — Мінімальний хмарний. Напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, anthropic/claude-haiku-4-5
-CLOUD_AVG — Середній хмарний. Напр.: openai/gpt-5.4, google/gemini-2.5-pro, anthropic/claude-sonnet-4-6
-CLOUD_MAX — Максимальний хмарний. Напр.: openai/gpt-5.5, anthropic/claude-opus-4-8
-resolveModel — Знаходить перший непорожній model-id для запиту, починаючи з локальних, а потім переходить до хмарних варіантів.
-
-## Гарантії поведінки
-
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.