@7n/test 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.13.0] - 2026-07-05
+
+### Changed
+
+- lock
+- Ф3 виносу LLM-шару: @7n/test переведено на @nitra/llm-lib. pi-client.mjs (власний SDK-плюмбінг, exponential backoff, memory-retry 15/30/60с) і prompt-budget.mjs видалено; замість них тонкий адаптер lib/llm.mjs (callText/callAgent) поверх runOneShot/runAgentSkill пакета і budgetFor/capText/packBatch з @nitra/llm-lib/prompt-budget. Політика строго fail-fast: knobs N_PI_RETRY_*/N_PI_MEMORY_RETRY_* видалено, лишилось одноразове подвоєння maxTokens на stopReason:'length'. coverage-fix переведено зі spawnSync pi CLI на SDK-embed агента. Тир-резолюцію централізовано (LOCAL_MIN/CLOUD_MIN/CLOUD_MAX з @nitra/llm-lib/model-tiers; classify приймає інжектовні tier1/tier2). УВАГА: потребує опублікованого @nitra/llm-lib >= 1.0.0 (мердж cursor#llm-lib-extraction перед релізом).
+
+## [0.12.2] - 2026-07-05
+
+### Changed
+
+- test(core): інваріантні тести маршрутизації gen-tests (local→cloud fallback, complex→cloud) замість сирих лічильників викликів; переписаний тест n-cursor-adr pi-extension
+
 ## [0.12.1] - 2026-07-04
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/test",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "CLI-утиліта @7n/test",
   "keywords": [
     "7n",
@@ -41,6 +41,7 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.3",
     "@nitra/check-env": "^4.2.1",
+    "@nitra/llm-lib": "^1.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "rollup": "^4.62.2",
     "vitest": "^4.1.9",

package/src/assess-need.mjs

@@ -6,7 +6,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { callText } from './lib/pi-client.mjs'
+import { callText } from './lib/llm.mjs'
 
 const MAX_CONTENT_BYTES = 6000
 
@@ -36,13 +36,12 @@ const WIRING_RE = /^(import\b|export\s+(?:\{[^}]*\}|\*|type\b|interface\b|enum\b
  * @returns {string}
  */
 function stripComments(src) {
-  return src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, '')
+  return src.replaceAll(/\/\*[\s\S]*?\*\//g, ' ').replaceAll(/\/\/[^\n]*/g, '')
 }
 
 /**
  * Fast local classifier — no I/O, no LLM.
  * Returns a result object for obvious cases, or null when ambiguous.
- *
  * @param {string} content file source
  * @returns {{ needsTests: boolean, reason: string } | null}
  */
@@ -109,7 +108,6 @@ async function assessOne(fileInfo, dir, callTextFn) {
  * Assess a list of uncovered files: do they need tests?
  * Obvious cases (re-exports, functions-with-branches) are resolved locally.
  * Only ambiguous files trigger an LLM call.
- *
  * @param {Array<{file: string, pct: number}>} files
  * @param {string} dir project root
  * @param {{ callText?: Function }} [opts]

package/src/coverage-classify/docs/index.md

@@ -3,11 +3,8 @@ type: JS Module
 title: index.mjs
 resource: npm/src/coverage-classify/index.mjs
 docgen:
-  crc: b7eff232
+  crc: bc7320ff
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд

package/src/coverage-classify/index.mjs

@@ -7,10 +7,10 @@
  *   3. Tier 1 fail → Tier 2 (N_CLOUD_MIN_MODEL через pi) → parseVerdict.
  *   4. Tier 2 fail → conservative fallback worth-testing/confidence=0.
  */
-import { env } from 'node:process'
 import { join } from 'node:path'
 
-import { callText } from '../lib/pi-client.mjs'
+import { callText } from '../lib/llm.mjs'
+import { CLOUD_MIN, LOCAL_MIN } from '@nitra/llm-lib/model-tiers'
 import { deriveCacheKey, readCache, writeCache } from './cache.mjs'
 import { buildUserPrompt, SYSTEM_PROMPT } from './prompt.mjs'
 import { parseVerdict } from './verdict-schema.mjs'
@@ -29,22 +29,22 @@ const FALLBACK_VERDICT = {
  * @returns {Promise<string>}
  */
 function callModel(prompt, model, cwd) {
-  return callText(prompt, { cwd, ...(model ? { model } : {}) })
+  return callText(prompt, { cwd, ...(model && { model }) })
 }
 
 /**
- * Два тири: N_LOCAL_MIN_MODEL → N_CLOUD_MIN_MODEL → FALLBACK_VERDICT.
+ * Два тири: tier1 (local-min) → tier2 (cloud-min) → FALLBACK_VERDICT.
  * @param {{file: string, mutants: object[]}} group
  * @param {object} mutant
  * @param {string} cwd
  * @param {(prompt: string, model: string, cwd: string) => Promise<string>} callModelFn
+ * @param {string} tier1 model-spec першого тиру ('' = pi-дефолт)
+ * @param {string} tier2 model-spec другого тиру ('' = pi-дефолт)
  * @returns {Promise<object>} verdict
  */
-async function classifyOne(group, mutant, cwd, callModelFn) {
+async function classifyOne(group, mutant, cwd, callModelFn, tier1, tier2) {
   const prompt = `${SYSTEM_PROMPT}\n\n${buildUserPrompt({ ...mutant, file: group.file }, cwd)}`
   const loc = `${group.file}:${mutant.line}:${mutant.col}`
-  const tier1 = env.N_LOCAL_MIN_MODEL ?? ''
-  const tier2 = env.N_CLOUD_MIN_MODEL ?? ''
 
   try {
     const text = await callModelFn(prompt, tier1, cwd)
@@ -64,14 +64,16 @@ async function classifyOne(group, mutant, cwd, callModelFn) {
  * Класифікує survived мутантів через pi (N_LOCAL_MIN_MODEL → N_CLOUD_MIN_MODEL → fallback).
  * @param {Array<{file: string, mutants: object[], exampleTest?: object|null, recommendationText?: string|null}>} survived
  * @param {string} cwd
- * @param {{cachePath?: string, callModel?: (prompt: string, model: string, cwd: string) => Promise<string>}} [opts]
+ * @param {{cachePath?: string, callModel?: (prompt: string, model: string, cwd: string) => Promise<string>,
+ *   tier1?: string, tier2?: string}} [opts] `tier1`/`tier2` — явні model-specs (дефолт: LOCAL_MIN/CLOUD_MIN пакета;
+ *   інжектовні, бо тир-константи фіксуються при імпорті й у тестах не стабляться через env)
  * @returns {Promise<Array<{key: string, verdict: object}>>}
  */
 export async function classify(survived, cwd, opts = {}) {
   const cachePath = opts.cachePath ?? join(cwd, 'npm/reports/coverage-classify.cache.json')
   const callModelFn = opts.callModel ?? callModel
-  const tier1 = env.N_LOCAL_MIN_MODEL ?? ''
-  const tier2 = env.N_CLOUD_MIN_MODEL ?? ''
+  const tier1 = opts.tier1 ?? LOCAL_MIN
+  const tier2 = opts.tier2 ?? CLOUD_MIN
   const cacheModel = `${tier1 || 'default'}+${tier2 || 'cloud'}`
 
   const cache = readCache(cachePath)
@@ -93,11 +95,11 @@ export async function classify(survived, cwd, opts = {}) {
           verdict: cached.verdict,
           confidence: cached.confidence,
           reason: cached.reason,
-          ...(cached.suggestedTest ? { suggestedTest: cached.suggestedTest } : {})
+          ...(cached.suggestedTest && { suggestedTest: cached.suggestedTest })
         }
       }
       if (!verdict) {
-        verdict = await classifyOne(group, mutant, cwd, callModelFn)
+        verdict = await classifyOne(group, mutant, cwd, callModelFn, tier1, tier2)
         if (cacheKey) {
           cache.entries[cacheKey] = { ...verdict, classifiedAt: new Date().toISOString() }
         }

package/src/coverage-fix.mjs

@@ -8,10 +8,11 @@
  */
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
+import { CLOUD_MAX } from '@nitra/llm-lib/model-tiers'
+import { callAgent } from './lib/llm.mjs'
 
-const MODEL = env.N_CURSOR_COVERAGE_FIX_MODEL ?? env.N_CLOUD_MAX_MODEL ?? ''
+const MODEL = env.N_CURSOR_COVERAGE_FIX_MODEL ?? CLOUD_MAX
 
 /**
  * @typedef {{line:number, col:number, mutantType:string, original:string, replacement:string}} MutantDetail
@@ -22,7 +23,7 @@ const MODEL = env.N_CURSOR_COVERAGE_FIX_MODEL ?? env.N_CLOUD_MAX_MODEL ?? ''
  * Запускає pi-агента для написання тестів по вцілілих мутантах.
  * @param {SurvivedFileGroup[]} survived вцілілі мутанти, згруповані по файлах
  * @param {string} projectRoot абсолютний шлях до кореня проєкту
- * @param {{ callPi?: (prompt: string, model: string, opts: { cwd: string }) => void }} [opts] ін'єкції для тестів
+ * @param {{ callPi?: (prompt: string, model: string, opts: { cwd: string }) => Promise<void> }} [opts] ін'єкції для тестів
  * @returns {Promise<void>}
  */
 export async function fixSurvivedMutants(survived, projectRoot, opts = {}) {
@@ -36,22 +37,19 @@ export async function fixSurvivedMutants(survived, projectRoot, opts = {}) {
   console.log(`\n🤖 coverage --fix: запускаю агента для ${totalMutants} вцілілих мутантів...\n`)
 
   const callPiFn = opts.callPi ?? callPi
-  callPiFn(prompt, MODEL, { cwd: projectRoot })
+  await callPiFn(prompt, MODEL, { cwd: projectRoot })
 }
 
 /**
- * Викликає pi в агентному режимі з live-output до stdout.
+ * Викликає агента через @nitra/llm-lib (SDK-embed, live-output до stdout) —
+ * заміна колишнього spawnSync pi CLI.
  * @param {string} prompt текст промпта
  * @param {string} model  provider/model-id або '' для pi-дефолту
  * @param {{ cwd?: string }} [piOpts] опційні параметри (cwd)
+ * @returns {Promise<void>} завершується після виконання агента
  */
 function callPi(prompt, model, { cwd } = {}) {
-  const modelArgs = model ? ['--model', model] : []
-  spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session'], {
-    cwd,
-    stdio: 'inherit',
-    timeout: 900_000
-  })
+  return callAgent(prompt, cwd, { model })
 }
 
 /**

package/src/docs/assess-need.md

@@ -3,11 +3,8 @@ type: JS Module
 title: assess-need.mjs
 resource: npm/src/assess-need.mjs
 docgen:
-  crc: 02dd5f01
+  crc: 960f8332
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
-  issues: internal-name:callText,judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд

package/src/docs/coverage-fix.md

@@ -3,11 +3,8 @@ type: JS Module
 title: coverage-fix.mjs
 resource: npm/src/coverage-fix.mjs
 docgen:
-  crc: 8b198273
+  crc: d0a20c67
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд

package/src/docs/fix-tests.md

@@ -3,12 +3,8 @@ type: JS Module
 title: fix-tests.mjs
 resource: npm/src/fix-tests.mjs
 docgen:
-  crc: f82de3c4
+  crc: 6597b7fc
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min-retry
-  score: 90
-  issues: internal-name:callText,judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд

package/src/docs/gen-tests.md

@@ -3,11 +3,8 @@ type: JS Module
 title: gen-tests.mjs
 resource: npm/src/gen-tests.mjs
 docgen:
-  crc: 0d24dc95
+  crc: 99d3e9b7
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд

package/src/fix-tests.mjs

@@ -19,13 +19,14 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join, relative } from 'node:path'
 import { env } from 'node:process'
-import { callText, MEMORY_ERROR_RE } from './lib/pi-client.mjs'
-import { budgetFor, capText, packBatch } from './lib/prompt-budget.mjs'
+import { callText, MEMORY_ERROR_RE } from './lib/llm.mjs'
+import { CLOUD_MAX } from '@nitra/llm-lib/model-tiers'
+import { budgetFor, capText, packBatch } from '@nitra/llm-lib/prompt-budget'
 import { findTestRules } from './gen-tests.mjs'
 import { parseFailingTests } from './coverage-per-file.mjs'
 import { resolveVitestRun } from './lib/vitest-shim.mjs'
 
-const MODEL = env.N_CURSOR_FIX_TESTS_MODEL ?? env.N_CLOUD_MAX_MODEL ?? undefined
+const MODEL = env.N_CURSOR_FIX_TESTS_MODEL ?? (CLOUD_MAX || undefined)
 const MAX_SRC_BYTES = 4000
 const TEST_DIR_MARKERS = ['/tests/', '\\tests\\']
 const TEST_FILE_SUFFIX = '.test.mjs'

package/src/gen-tests.mjs

@@ -16,13 +16,13 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
 import { join, relative, dirname } from 'node:path'
-import { callText, MEMORY_ERROR_RE } from './lib/pi-client.mjs'
-import { budgetFor } from './lib/prompt-budget.mjs'
+import { callText, MEMORY_ERROR_RE } from './lib/llm.mjs'
+import { env } from 'node:process'
+import { budgetFor } from '@nitra/llm-lib/prompt-budget'
 import { resolveVitestRun } from './lib/vitest-shim.mjs'
 import { extractExportsWithComplexity } from './classify-exports.mjs'
 import { analyzeModule } from './lib/ast-analyze.mjs'
 import { probeModule, probeFetchCalls, probeTimeVariants, probeHelpers } from './lib/runtime-probe.mjs'
-import { env } from 'node:process'
 
 const MAX_SRC_BYTES = 6000
 

package/src/lib/docs/index.md

@@ -9,7 +9,6 @@ resource: npm/src/lib/
 | Файл                                  | Тип       |
 | ------------------------------------- | --------- |
 | [ast-analyze.mjs](ast-analyze.md)     | JS Module |
-| [pi-client.mjs](pi-client.md)         | JS Module |
-| [prompt-budget.mjs](prompt-budget.md) | JS Module |
+| [llm.mjs](llm.md)                     | JS Module |
 | [runtime-probe.mjs](runtime-probe.md) | JS Module |
 | [vitest-shim.mjs](vitest-shim.md)     | JS Module |

package/src/lib/docs/llm.md

@@ -0,0 +1,23 @@
+---
+type: JS Module
+title: llm.mjs
+resource: npm/src/lib/llm.mjs
+docgen:
+  crc: 41c6ec97
+---
+
+## Огляд
+
+Тонкий адаптер @7n/test над пакетом `@nitra/llm-lib` (Ф3 спеки llm-lib-extraction у репо cursor): зберігає звичний контракт `callText`/`callAgent` для внутрішніх колерів (gen-tests, fix-tests, assess-need, coverage-classify, coverage-fix), а транспорт, registry і трасування повністю живуть у пакеті. Замінив колишній `pi-client.mjs` з власним SDK-плюмбінгом, retry/backoff і прямим omlx-HTTP.
+
+## Поведінка
+
+callText — одноразовий text-виклик без tools через `runOneShot`: повертає текст відповіді; кидає Error на будь-якій помилці виклику (fail-fast, без retry/backoff). Єдина локальна політика — одноразове подвоєння `maxTokens` (до стелі 32768) при обрізаній відповіді (`stopReason: 'length'`), без пауз.
+callAgent — агентний виклик через `runAgentSkill` з повним tool-set (read/write/edit/bash/grep/find/ls): агент пише файли напряму, текст стрімиться у stdout; таймаут 900с (паритет зі старим spawnSync pi CLI); без стелі відповіді (`maxTokens: 0`). Кидає Error на помилці.
+MEMORY_ERROR_RE — реекспорт з пакета: колери класифікують memory-guard помилку локального model-сервера (пробити нагору й завершити процес, а не ковтати як per-file помилку).
+
+## Гарантії поведінки
+
+- Жодних вбудованих retry/backoff: колишні knobs N_PI_RETRY_ATTEMPTS/N_PI_MEMORY_RETRY_ATTEMPTS тощо видалено (fail-fast політика пакета).
+- Подвоєння maxTokens відбувається щонайбільше один раз на виклик.
+- `opts.deps` прокидається у раннери пакета — тести інжектять фейк-сесії без pi.

package/src/lib/llm.mjs

@@ -0,0 +1,83 @@
+/**
+ * Тонкий адаптер @7n/test над @nitra/llm-lib (Ф3 спеки llm-lib-extraction):
+ * зберігає звичний контракт `callText`/`callAgent` для внутрішніх колерів,
+ * але транспорт/registry/trace повністю живуть у пакеті.
+ *
+ * Політика fail-fast успадковується від пакета: жодних retry/backoff на
+ * connection- чи memory-помилках (колишні knobs N_PI_RETRY_ATTEMPTS,
+ * N_PI_MEMORY_RETRY_ATTEMPTS тощо видалено разом із withRetry).
+ * Єдина локальна політика — одноразове
+ * подвоєння `maxTokens` на обрізаній відповіді (`stopReason: 'length'`):
+ * це семантичний повтор без пауз, а не очікування зайнятого сервера.
+ */
+import { MEMORY_ERROR_RE, runOneShot } from '@nitra/llm-lib/one-shot'
+import { runAgentSkill } from '@nitra/llm-lib/agent-skill'
+
+export { MEMORY_ERROR_RE }
+
+/**
+ * Стеля відповіді моделі для подвоєння на `stopReason: 'length'` — межа
+ * `maxTokens` реєстру для локальної моделі (див. `~/.pi/agent/models.json`).
+ */
+const MAX_TOKENS_CEILING = 32_768
+
+/** Таймаут агентного виклику (паритет зі старим spawnSync pi CLI). */
+const AGENT_TIMEOUT_MS = 900_000
+
+/**
+ * Одноразовий text-виклик (без tools). Кидає Error на будь-якій помилці
+ * виклику (колери класифікують memory-guard через `MEMORY_ERROR_RE`).
+ * @param {string} prompt текст запиту для моделі
+ * @param {object} [opts] додаткові параметри виклику
+ * @param {string} [opts.cwd] робоча директорія для session
+ * @param {string} [opts.model] provider/model-id (напр. "openai/gpt-5.5"); без значення — default pi
+ * @param {number} [opts.maxTokens] стеля відповіді для цього виклику; на
+ *   `stopReason: 'length'` виклик повторюється один раз із подвоєною стелею
+ * @param {object} [opts.deps] інжекти для тестів (прокидаються у runOneShot)
+ * @returns {Promise<string>} текстова відповідь моделі
+ */
+export async function callText(prompt, opts = {}) {
+  const r = await runOneShot({
+    messages: [{ role: 'user', content: prompt }],
+    modelSpec: opts.model ?? '',
+    maxTokens: opts.maxTokens,
+    timeoutMs: 0,
+    cwd: opts.cwd,
+    caller: '7n-test:text',
+    deps: opts.deps
+  })
+  if (r.error) throw new Error(r.error)
+
+  // Обрізана генерація зі зниженою стелею — не палимо retry-цикли колера
+  // на «invalid block», а один раз повторюємо з подвоєною стелею.
+  if (r.stopReason === 'length' && opts.maxTokens && opts.maxTokens < MAX_TOKENS_CEILING && !opts._lengthRetried) {
+    const doubled = Math.min(opts.maxTokens * 2, MAX_TOKENS_CEILING)
+    console.log(`  ⚠ відповідь обрізана (stopReason: length) — повтор із maxTokens ${opts.maxTokens} → ${doubled}`)
+    return callText(prompt, { ...opts, maxTokens: doubled, _lengthRetried: true })
+  }
+  return r.content
+}
+
+/**
+ * Агентний виклик із повним tool-set (read/write/edit/bash/grep/find/ls):
+ * агент пише файли напряму, текст стрімиться у stdout. Кидає Error на
+ * помилці виклику. Заміна колишнього `spawnSync('pi', ['-p', ...])`.
+ * @param {string} prompt текст завдання для агента
+ * @param {string} cwd робоча директорія, куди агент може писати файли
+ * @param {object} [opts] додаткові параметри
+ * @param {string} [opts.model] provider/model-id або '' для pi-дефолту
+ * @param {object} [opts.deps] інжекти для тестів (прокидаються у runAgentSkill)
+ * @returns {Promise<void>} проміс завершується після виконання агента
+ */
+export async function callAgent(prompt, cwd, opts = {}) {
+  const r = await runAgentSkill(prompt, {
+    skillId: '7n-test',
+    modelSpec: opts.model ?? '',
+    cwd,
+    timeoutMs: AGENT_TIMEOUT_MS,
+    maxTokens: 0, // без стелі: агент пише цілі тест-файли (паритет зі старим CLI-шляхом)
+    caller: 'agent:7n-test',
+    deps: opts.deps
+  })
+  if (r.error) throw new Error(r.error)
+}

package/src/lib/docs/pi-client.md

@@ -1,29 +0,0 @@
----
-type: JS Module
-title: pi-client.mjs
-resource: npm/src/lib/pi-client.mjs
-docgen:
-  crc: e7f3471e
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Цей модуль надає прямий, інпроцесний програмний інтерфейс для взаємодії з агентами pi SDK, замінюючи синхронні виклики зовнішнього процесу. Він реалізує два режими роботи: текстовий режим, де функція `callText` повертає рядок на основі текстового запиту без активації інструментів, та режим агента, де функція `callAgent` активує кодові інструменти для прямого внесення змін у файли у заданій робочій директорії. Зверніть увагу, що у цьому інтерфейсі відсутній механізм кешування.
-
-## Поведінка
-
-callText відправляє текстовий запит до моделі pi та повертає текстову відповідь.
-callAgent відправляє завдання до агента pi з активними інструментами кодування та виконує зміни у файлах у вказаній директорії.
-
-## Публічний API
-
-callText — надсилає одноразовий запит у текстовому режимі, не використовуючи інструменти, і повертає відповідь, зчитуючи конфігурацію з ~/.pi/.
-callAgent — надсилає запит у режимі агента, надаючи доступ до повного набору інструментів кодування (читання, запис, bash, редагування); агент сам створює тестові файли.
-
-## Гарантії поведінки
-
-- (специфічних машинно-виведених гарантій немає)

package/src/lib/docs/prompt-budget.md

@@ -1,34 +0,0 @@
----
-type: JS Module
-title: prompt-budget.mjs
-resource: npm/src/lib/prompt-budget.mjs
-docgen:
-  crc: 010265bd
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Слугує єдиною точкою правди для визначення ліміту символів промпту та стелі відповіді (`maxTokens`) залежно від типу задачі (наприклад, `gen-tests`, `fix-tests`). Це механізм захисту від надмірного розширення промпту. Надає функції для внутрішнього обрізання тексту (`fitToBudget`), що виключає низькопріоритетні частини промпту, щоб він вмістився у встановлений ліміт, а також для ефективного групування цілих одиниць вмісту (`packBatch`) для подальшої пакетної обробки.
-
-## Поведінка
-
-Поведінка
-budgetFor повертає встановлений ліміт символів для промпту та максимальну кількість токенів для заданого типу LLM-задачі.
-capText обрізає вхідний текст до заданого максимального розміру, зберігаючи його структуру з головною та хвостовою частинами, розділеними маркером.
-fitToBudget збирає частини промпту, обрізаючи або відкидаючи нижчопріоритетні частини доти, доки сумарний обсяг не вкладеться у заданий ліміт символів, при цьому найвищий пріоритет завжди захищено.
-packBatch групує одиниці (файли) у батчи, сортуючи їх за розміром, щоб вмістити якомога більше у межах заданого бюджету; одиниці, що не вмістилися, відкладаються для наступного проходу.
-
-## Публічний API
-
-budgetFor — надає бюджет, необхідний для певної категорії завдання.
-capText — безпечно укорочує текст, зберігаючи його початок, маркер та кінець.
-fitToBudget — розміщує блоки у межах заданого бюджету: спочатку зменшує вміст, а потім відкидає найнижчі за пріоритетом, поки обсяг не втиснеться. Найважливіший елемент завжди залишається повним.
-packBatch — згруповує файли для обробки: спочатку обирає найменші для оптимізації кількості виправлень за один раз. Якщо елемент занадто великий, він відкладається для окремої обробки, де застосовується жорсткіше обрізання.
-
-## Гарантії поведінки
-
-- Read-only: не виконує операцій запису (ФС/БД).

package/src/lib/pi-client.mjs

@@ -1,243 +0,0 @@
-/**
- * Programmatic pi client via `@earendil-works/pi-coding-agent` SDK.
- * Replaces spawnSync('pi', ...) with direct in-process calls.
- *
- * Two modes:
- *   callText(prompt, model?)  — text-only, no tools, returns string
- *   callAgent(prompt, cwd)    — coding tools enabled, writes files directly
- *
- * Both retry transient connection failures (e.g. a shared local model server
- * that's momentarily busy under concurrent load) with exponential backoff
- * instead of failing the caller's file on the first hiccup. A memory-guard
- * rejection gets its own longer bounded backoff: oMLX (local model server)
- * одночасно, тож відмова зазвичай відображає залишкову пам'ять попереднього
- * запиту, яку сервер вивільняє сам за десятки секунд. Лише після
- * `N_PI_MEMORY_RETRY_ATTEMPTS` невдач тіло запиту друкується в stdout і
- * помилка прокидається як термінальна (виклики-власники процесу мають дати
- * їй впасти, не ковтати як звичайну per-file помилку).
- */
-import { createAgentSession, SessionManager, ModelRegistry, AuthStorage } from '@earendil-works/pi-coding-agent'
-import { randomInt } from 'node:crypto'
-import { env } from 'node:process'
-import { setTimeout as sleep } from 'node:timers/promises'
-
-let _registry = null
-/**
- * Повертає або ініціалізує спільний model registry для поточного процесу.
- * @returns {object} спільний registry
- */
-function getRegistry() {
-  if (_registry) return _registry
-  _registry = ModelRegistry.create(AuthStorage.create())
-  return _registry
-}
-
-const RETRYABLE_ERROR_RE = /connection error|ECONNREFUSED|ETIMEDOUT|fetch failed|network/i
-const OMLX_CODE_RE = /"(?:omlx_)?code"\s*:\s*"([^"]+)"/
-const OMLX_ESTIMATED_BYTES_RE = /"estimated_bytes"\s*:\s*(\d+)/
-const OMLX_LIMIT_BYTES_RE = /"limit_bytes"\s*:\s*(\d+)/
-/** Matches a local model server (e.g. oMLX) rejecting a prompt for lack of RAM. */
-export const MEMORY_ERROR_RE = /memory guard|memory limit|prefill would require/i
-const MAX_ATTEMPTS = Number(env.N_PI_RETRY_ATTEMPTS) || 4
-const BASE_DELAY_MS = Number(env.N_PI_RETRY_DELAY_MS) || 1500
-const MAX_DELAY_MS = 15_000
-/** Скільки разів пробуємо промпт, відкинутий memory guard (включно з першою спробою). */
-const MEMORY_MAX_ATTEMPTS = Number(env.N_PI_MEMORY_RETRY_ATTEMPTS) || 3
-/** Базова затримка перед повтором після memory-guard відмови (експоненційно: 15s → 30s → …). */
-const MEMORY_BASE_DELAY_MS = Number(env.N_PI_MEMORY_RETRY_DELAY_MS) || 15_000
-const MEMORY_MAX_DELAY_MS = 60_000
-
-/**
- * Витягує структуровані поля oMLX-помилки з тексту повідомлення, якщо тіло
- * 400 (`omlx_code`/`estimated_bytes`/`limit_bytes`) потрапило в message.
- * `estimated_bytes`/`limit_bytes` — байти GPU/Metal-пам'яті сервера,
- * ТІЛЬКИ для діагностики й логів (не «скільки символів промпту зрізати»).
- * @param {string} message текст помилки від SDK/сервера
- * @returns {{omlxCode?: string, estimatedBytes?: number, limitBytes?: number} | null} знайдені поля або `null`
- */
-function parseOmlxErrorDetails(message) {
-  const code = OMLX_CODE_RE.exec(message)?.[1]
-  const estimated = OMLX_ESTIMATED_BYTES_RE.exec(message)?.[1]
-  const limit = OMLX_LIMIT_BYTES_RE.exec(message)?.[1]
-  if (!code && !estimated && !limit) return null
-  const details = {}
-  if (code) details.omlxCode = code
-  if (estimated) details.estimatedBytes = Number(estimated)
-  if (limit) details.limitBytes = Number(limit)
-  return details
-}
-
-/**
- * Розпізнає memory-guard відмову і збагачує помилку структурованими полями
- * (`omlxCode`, `estimatedBytes`, `limitBytes`), коли вони доступні в message.
- * @param {Error} error помилка з виклику моделі
- * @returns {boolean} `true`, якщо це memory-guard відмова
- */
-function isMemoryGuardError(error) {
-  const details = parseOmlxErrorDetails(error.message ?? '')
-  if (details) Object.assign(error, details)
-  return error.omlxCode === 'prefill_memory_exceeded' || MEMORY_ERROR_RE.test(error.message ?? '')
-}
-
-/**
- * Термінальний вихід після вичерпання memory-retry: друкує тіло запиту в
- * stdout (лише тут — не на проміжних спробах) і кидає помилку далі,
- * зберігаючи структуровані поля й оригінал у `cause`. Виклики-власники
- * процесу (CLI) мають дати їй впасти, не ковтати як per-file помилку.
- * @param {Error} error memory-guard помилка останньої спроби
- * @param {string} requestBody промпт, надісланий моделі
- * @returns {never} завжди кидає
- */
-function failOnMemoryGuard(error, requestBody) {
-  console.log('--- omlx memory-guard: тіло запиту ---')
-  console.log(requestBody)
-  console.log(`✗ omlx memory-guard: ${error.message}`)
-  const wrapped = new Error(`omlx memory-guard: ${error.message}`, { cause: error })
-  for (const key of ['omlxCode', 'estimatedBytes', 'limitBytes']) {
-    if (error[key] !== undefined) wrapped[key] = error[key]
-  }
-  throw wrapped
-}
-
-/**
- * Retries `fn` with exponential backoff + jitter when it throws a transient
- * connection-ish error (shared local model server busy/restarting); other
- * errors (auth, malformed request) are re-thrown immediately. A memory-guard
- * rejection has its own bounded schedule (`MEMORY_MAX_ATTEMPTS` спроб,
- * затримки від `MEMORY_BASE_DELAY_MS` експоненційно): одно-слотова черга
- * oMLX вивільняє залишкову пам'ять попереднього запиту сама, тож повтор
- * того самого промпту після паузи легітимний. Після вичерпання —
- * `failOnMemoryGuard` (друк тіла + термінальний throw).
- * @template T
- * @param {() => Promise<T>} fn operation to retry
- * @param {string} requestBody prompt sent to the model, printed if a memory-guard error exhausts its retries
- * @returns {Promise<T>} result of the first successful attempt
- */
-async function withRetry(fn, requestBody) {
-  let memoryAttempts = 0
-  let connAttempts = 0
-  for (;;) {
-    try {
-      return await fn()
-    } catch (error) {
-      if (isMemoryGuardError(error)) {
-        memoryAttempts++
-        if (memoryAttempts >= MEMORY_MAX_ATTEMPTS) failOnMemoryGuard(error, requestBody)
-        const delay = Math.min(MEMORY_BASE_DELAY_MS * 2 ** (memoryAttempts - 1), MEMORY_MAX_DELAY_MS)
-        await sleep(delay * (0.5 + randomInt(5000) / 10000))
-        continue
-      }
-      connAttempts++
-      if (connAttempts >= MAX_ATTEMPTS || !RETRYABLE_ERROR_RE.test(error.message ?? '')) throw error
-      const delay = Math.min(BASE_DELAY_MS * 2 ** (connAttempts - 1), MAX_DELAY_MS)
-      const jitter = delay * (0.5 + randomInt(5000) / 10000)
-      await sleep(jitter)
-    }
-  }
-}
-
-/**
- * Стеля відповіді моделі для подвоєння на `stopReason: 'length'` — межа
- * `maxTokens` реєстру для локальної моделі (див. `~/.pi/agent/models.json`).
- */
-const MAX_TOKENS_CEILING = 32_768
-
-/**
- * Обгортає `session.agent.streamFn`, додаючи per-call `maxTokens` у
- * options LLM-виклику. SDK не має публічного per-call параметра
- * (спайк: `session.prompt(text, options)` не прокидає options у loop
- * config), але `options.maxTokens` у streamFn перекриває дефолт моделі —
- * перевірено на дроті через myllm-проксі (`max_completion_tokens`
- * змінюється).
- * @param {object} session сесія з `createAgentSession`
- * @param {number} maxTokens стеля відповіді для всіх викликів цієї сесії
- * @returns {void}
- */
-function applyMaxTokens(session, maxTokens) {
-  const orig = session.agent.streamFn
-  session.agent.streamFn = (model, context, options) => orig(model, context, { ...options, maxTokens })
-}
-
-/**
- * Sends a single prompt to pi in text mode (no tools) and returns the response.
- * Reads auth/model config from ~/.pi/ same as the CLI.
- * @param {string} prompt текст запиту для моделі
- * @param {object} [opts] додаткові параметри виклику
- * @param {string} [opts.cwd] робоча директорія для session
- * @param {string} [opts.model] provider/model-id для pi (наприклад, "openai/gpt-4o"); без значення — default pi
- * @param {number} [opts.maxTokens] стеля відповіді для цього виклику (перекриває дефолт моделі);
- *   на `stopReason: 'length'` (обрізана генерація) виклик повторюється один раз із подвоєною стелею
- * @returns {Promise<string>} текстова відповідь моделі
- */
-export async function callText(prompt, opts = {}) {
-  const result = await withRetry(async () => {
-    const cwd = opts.cwd ?? process.cwd()
-    const sessionOpts = {
-      tools: [],
-      sessionManager: SessionManager.inMemory(cwd),
-      cwd
-    }
-    if (opts.model) {
-      const registry = await getRegistry()
-      const slashIdx = opts.model.indexOf('/')
-      const provider = slashIdx === -1 ? null : opts.model.slice(0, slashIdx)
-      const modelId = slashIdx === -1 ? opts.model : opts.model.slice(slashIdx + 1)
-      const resolved = provider ? Reflect.apply(registry.find, registry, [provider, modelId]) : null
-      sessionOpts.modelRegistry = registry
-      sessionOpts.model = resolved ?? opts.model
-    }
-    const { session } = await createAgentSession(sessionOpts)
-    if (opts.maxTokens) applyMaxTokens(session, opts.maxTokens)
-    try {
-      await session.prompt(prompt)
-
-      const state = session.state
-      const last = state.messages.at(-1)
-      if (!last || last.role !== 'assistant') return { text: '', truncated: false }
-      if (last.stopReason === 'error' || last.stopReason === 'aborted') {
-        throw new Error(`pi error: ${last.errorMessage ?? last.stopReason}`)
-      }
-      return {
-        text: last.content
-          .filter(c => c.type === 'text')
-          .map(c => c.text)
-          .join(''),
-        truncated: last.stopReason === 'length'
-      }
-    } finally {
-      session.dispose()
-    }
-  }, prompt)
-
-  // Обрізана генерація зі зниженою стелею — не палимо retry-цикли колера
-  // на «invalid block», а один раз повторюємо з подвоєною стелею.
-  if (result.truncated && opts.maxTokens && opts.maxTokens < MAX_TOKENS_CEILING && !opts._lengthRetried) {
-    const doubled = Math.min(opts.maxTokens * 2, MAX_TOKENS_CEILING)
-    console.log(`  ⚠ відповідь обрізана (stopReason: length) — повтор із maxTokens ${opts.maxTokens} → ${doubled}`)
-    return callText(prompt, { ...opts, maxTokens: doubled, _lengthRetried: true })
-  }
-  return result.text
-}
-
-/**
- * Sends a prompt to pi in agent mode with full coding tools (read/write/bash/edit).
- * The agent writes test files directly — no need to parse output.
- * @param {string} prompt текст завдання для агента
- * @param {string} cwd робоча директорія, куди агент може писати файли
- * @returns {Promise<void>} проміс завершується після виконання агента
- */
-export function callAgent(prompt, cwd) {
-  return withRetry(async () => {
-    const { session } = await createAgentSession({
-      tools: ['read', 'write', 'edit', 'bash', 'grep', 'find', 'ls'],
-      sessionManager: SessionManager.inMemory(cwd),
-      cwd
-    })
-
-    try {
-      await session.prompt(prompt)
-    } finally {
-      session.dispose()
-    }
-  }, prompt)
-}

package/src/lib/prompt-budget.mjs

@@ -1,131 +0,0 @@
-/**
- * Спільний бюджет LLM-промптів (фаза 2 спеки
- * `docs/specs/2026-07-04-omlx-prompt-budget.md`, Д3): єдина точка правди
- * для ліміту символів промпту та стелі відповіді (`maxTokens`) за типом
- * задачі. Захищає від класу проблем «безлімітна секція роздула промпт до
- * memory guard» — кожен колер (gen-tests, fix-tests) бере бюджет звідси
- * замість власних розрізнених констант.
- *
- * Дві незалежні утиліти:
- * - `fitToBudget` — внутрішньопромптове обрізання: дропає/вкорочує
- *   низькопріоритетні chunks, поки промпт не влізе в ліміт;
- * - `packBatch` — батчинг цілих одиниць (файлів): скільки влазить зараз,
- *   решта — у наступний прохід.
- */
-
-/** Бюджети за типом задачі: ліміт символів промпту і стеля відповіді. */
-const BUDGETS = {
-  header: { maxPromptChars: 8000, maxTokens: 2048 },
-  block: { maxPromptChars: 40_000, maxTokens: 8192 },
-  'single-file': { maxPromptChars: 60_000, maxTokens: 16_384 },
-  fix: { maxPromptChars: 60_000, maxTokens: 16_384 }
-}
-
-/** Частка голови chunk-а, що лишається при обрізанні (решта — хвіст + маркер). */
-const TRUNCATE_HEAD_RATIO = 0.7
-/** Мінімальний розмір, до якого має сенс обрізати chunk (менше — просто дроп). */
-const MIN_TRUNCATED_CHARS = 400
-
-/**
- * Повертає бюджет для типу задачі.
- * @param {'header'|'block'|'single-file'|'fix'} taskKind тип LLM-задачі
- * @returns {{maxPromptChars: number, maxTokens: number}} копія бюджету
- */
-export function budgetFor(taskKind) {
-  const budget = BUDGETS[taskKind]
-  if (!budget) throw new Error(`prompt-budget: невідомий taskKind "${taskKind}"`)
-  return { ...budget }
-}
-
-/**
- * Символьно-безпечне обрізання середини: голова + маркер + хвіст.
- * @param {string} text вихідний текст
- * @param {number} maxChars цільовий розмір
- * @returns {string} обрізаний текст із маркером
- */
-export function capText(text, maxChars) {
-  return truncateMiddle(text, maxChars)
-}
-
-/**
- * Внутрішня реалізація `capText` (окреме ім'я — щоб `fitToBudget` не
- * залежав від публічного контракту).
- * @param {string} text вихідний текст
- * @param {number} maxChars цільовий розмір
- * @returns {string} обрізаний текст із маркером
- */
-function truncateMiddle(text, maxChars) {
-  const chars = [...text]
-  if (chars.length <= maxChars) return text
-  const head = Math.floor(maxChars * TRUNCATE_HEAD_RATIO)
-  const tail = Math.max(0, maxChars - head)
-  const dropped = chars.length - head - tail
-  return `${chars.slice(0, head).join('')}\n...[обрізано ${dropped} символів]...\n${chars.slice(chars.length - tail).join('')}`
-}
-
-/**
- * Вкладає chunks у бюджет: спершу обрізає, потім дропає найнижчі
- * пріоритети, поки сумарний текст не влізе. Chunk із НАЙВИЩИМ
- * пріоритетом (сама задача / останній user-запит) захищений — його
- * текст не ріжеться і не дропається ніколи.
- * @param {Array<{text: string, priority: number, label?: string}>} chunks частини промпту; нижчий priority ріжеться першим
- * @param {number} maxChars бюджет символів на весь результат
- * @returns {{text: string, dropped: string[]}} зібраний промпт + мітки скорочених/викинутих частин
- */
-export function fitToBudget(chunks, maxChars) {
-  const parts = chunks.map((c, i) => ({ ...c, label: c.label ?? `chunk#${i}`, kept: true, out: c.text }))
-  const maxPriority = Math.max(...parts.map(p => p.priority))
-  const total = () => parts.filter(p => p.kept).reduce((sum, p) => sum + p.out.length + 1, 0)
-  const dropped = []
-
-  const candidates = parts.filter(p => p.priority < maxPriority).toSorted((a, b) => a.priority - b.priority)
-  // Прохід 1: обрізати кандидатів (від найнижчого пріоритету)
-  for (const part of candidates) {
-    if (total() <= maxChars) break
-    const overflow = total() - maxChars
-    const target = Math.max(MIN_TRUNCATED_CHARS, part.out.length - overflow)
-    if (part.out.length > target) {
-      part.out = truncateMiddle(part.out, target)
-      dropped.push(`${part.label} (обрізано)`)
-    }
-  }
-  // Прохід 2: дропнути кандидатів цілком, якщо обрізання не вистачило
-  for (const part of candidates) {
-    if (total() <= maxChars) break
-    part.kept = false
-    dropped.push(`${part.label} (видалено)`)
-  }
-
-  return {
-    text: parts
-      .filter(p => p.kept)
-      .map(p => p.out)
-      .join('\n'),
-    dropped
-  }
-}
-
-/**
- * Пакує одиниці (файли) у бюджет: найменші першими, щоб максимізувати
- * кількість виправлень за один виклик. Одиниця, що сама-одна перевищує
- * бюджет, потрапляє в `deferred` — колер робить для неї соло-виклик із
- * жорсткішим внутрішнім обрізанням (`fitToBudget`), а не мовчазний skip.
- * @param {Array<{key: string, size: number}>} items одиниці з розмірами
- * @param {number} maxChars бюджет символів на батч
- * @returns {{included: string[], deferred: string[]}} ключі включених і відкладених одиниць
- */
-export function packBatch(items, maxChars) {
-  const sorted = items.toSorted((a, b) => a.size - b.size)
-  const included = []
-  const deferred = []
-  let used = 0
-  for (const item of sorted) {
-    if (item.size + (included.length === 0 ? 0 : used) <= maxChars) {
-      included.push(item.key)
-      used += item.size
-    } else {
-      deferred.push(item.key)
-    }
-  }
-  return { included, deferred }
-}