@7n/llm-lib 2.13.0 → 2.13.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.13.2] - 2026-07-29
+
+### Changed
+
+- Уніфіковано вибір моделей через `resolveModel`: явні local/cloud selectors
+використовують спільну Rust-драбину, а one-shot і agent runners вимагають
+tier або explicit model policy.
+
+## [2.13.1] - 2026-07-29
+
+### Fixed
+
+- local-providers.test: герметизація від ambient N_OMLX_*/N_LITELLM_* env (тест «без env» падав на машинах зі справжнім N_LITELLM_API_KEY)
+
 ## [2.13.0] - 2026-07-29
 
 ### Changed

package/lib/acp.mjs

@@ -10,8 +10,7 @@
  * watchdog-поведінкою на мертвий/незапущений дочірній процес.
  *
  * `claude` тут немає — Rust-крейт моделює лише `cursor`/`codex`/`pi`
- * (`AcpAgentKind`); deprecated `claude`-раннер лишається окремим
- * JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
+ * (`AcpAgentKind`); `claude` тут навмисно не підтримується.
  */
 import { loadNative } from './internal/native.mjs'
 
@@ -20,17 +19,19 @@ import { loadNative } from './internal/native.mjs'
  * рішення И) — опційний абстрактний тир (`min`/`avg`/`max`): якщо заданий,
  * Rust сам резолвить tier→env/args/post-session-config з пресету агента
  * (`one_shot_acp_with_tier`) — жодного JS-хелпера "пресет→env" тут немає.
- * Без `tier` — стара поведінка (модель = персональний конфіг CLI на машині).
+ * Без `tier` виклик заборонений, крім явного `mode:'interactive'` для персонального CLI-конфіга.
  * @param {'cursor' | 'codex' | 'pi'} kind провайдер
  * @param {string} prompt промпт
  * @param {string} cwd робочий каталог сесії агента (каталог проєкту-викликача)
  * @param {{
- *   tier?: 'min' | 'avg' | 'max',
+ *   tier?: 'min' | 'avg' | 'max', mode?: 'interactive',
  *   native?: { oneShotAcp: (kind: string, prompt: string, cwd: string, tier?: string) => Promise<string> }
  * }} [options] тир + інжект `native` для тестів (той самий 4-й аргумент, що й раніше — сумісність зі старим `{ native }`-викликом збережена)
  * @returns {Promise<string>} повний текст відповіді до кінця ходу
  */
-export function runAcpAgent(kind, prompt, cwd, { tier, native } = {}) {
+export function runAcpAgent(kind, prompt, cwd, { tier, mode, native } = {}) {
+  if (!tier && mode !== 'interactive') throw new TypeError('runAcpAgent: передай tier або явно mode:"interactive"')
+  if (tier && mode) throw new TypeError('runAcpAgent: tier і mode взаємовиключні')
   const nativeImpl = native ?? loadNative()
   return nativeImpl.oneShotAcp(kind, prompt, cwd, tier)
 }

package/lib/agent-skill.mjs

@@ -6,7 +6,7 @@
  * Виконує один скіл як pi-агента: готовий промпт-рядок → `session.prompt`.
  * Повний user-trust набір вбудованих tools (`read/grep/find/edit/write/ls/bash`), БЕЗ
  * write-guard — скіл є явною user-invocation (паритет із `claude -p`, який теж без
- * обмежень). Модель — з ОДНОГО тиру (дефолт `max`), без escalation-сходів fix-engine.
+ * обмежень). Модель задається явним тиром або `modelSpec`, без escalation-сходів fix-engine.
  * Runaway-backstop: turn-ceiling + per-call timeout. Асистентський текст стрімиться
  * у stdout (паритет із `claude -p`). Телеметрія `kind:"skill"` у глобальний trace.
  *
@@ -80,7 +80,7 @@ async function defaultCreateSession({ registry, model, cwd, thinkingLevel, maxTo
 export async function runAgentSkill(prompt, opts = {}) {
   const {
     skillId = 'skill',
-    tier = 'max',
+    tier,
     modelSpec,
     cwd = process.cwd(),
     thinkingLevel,
@@ -122,7 +122,8 @@ export async function runAgentSkill(prompt, opts = {}) {
   let model
   try {
     registry = deps.registry ?? (await getReg())
-    spec = modelSpec ?? resolveModel(tier) // '' допустимо → дефолт провайдера pi
+    if (!modelSpec && !tier) return fail('model selection: передай tier або явний modelSpec', null)
+    spec = modelSpec || resolveModel(tier)
     model = spec ? resolveModelSpec(registry, spec) : null
     if (spec && !model) return fail(`модель не знайдена: ${spec}`, spec)
   } catch (error) {

package/lib/batch.mjs

@@ -29,8 +29,8 @@ import { loadNative } from './internal/native.mjs'
 /**
  * Batch-виклик Типу 2b. `modelSpecOrTier` — той самий контракт, що й у
  * [`oneShotLocalCloud`] з `local-cloud.mjs`: явний `"provider/model-id"`
- * або абстрактний тир (`min`/`avg`/`max`).
- * @param {string} modelSpecOrTier `"provider/model-id"` або `'min'|'avg'|'max'`
+ * абстрактний тир (`min`/`avg`/`max`) або явний env-selector.
+ * @param {string} modelSpecOrTier `"provider/model-id"`, tier або env-selector
  * @param {BatchItem[]} items вхідні items (`customId` — унікальний у межах виклику)
  * @param {{
  *   localProviders?: Record<string, { baseUrl: string, apiKey?: string | null }>,

package/lib/docs/acp.md

@@ -3,9 +3,9 @@ type: JS Module
 title: acp.mjs
 resource: llm-lib/lib/acp.mjs
 docgen:
-  crc: 1ed416a1
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min
+  crc: 022452f4
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 80
 ---
 
@@ -22,8 +22,7 @@ ACP JSON-RPC/`ClientSideConnection` тут; уся протокольна лог
 watchdog-поведінкою на мертвий/незапущений дочірній процес.
 
 `claude` тут немає — Rust-крейт моделює лише `cursor`/`codex`/`pi`
-(`AcpAgentKind`); deprecated `claude`-раннер лишається окремим
-JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
+(`AcpAgentKind`); `claude` тут навмисно не підтримується.
 
 ## Публічний API
 
@@ -31,11 +30,11 @@ JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
 рішення И) — опційний абстрактний тир (`min`/`avg`/`max`): якщо заданий,
 Rust сам резолвить tier→env/args/post-session-config з пресету агента
 (`one_shot_acp_with_tier`) — жодного JS-хелпера "пресет→env" тут немає.
-Без `tier` — стара поведінка (модель = персональний конфіг CLI на машині).
+Без `tier` виклик заборонений, крім явного `mode:'interactive'` для персонального CLI-конфіга.
 
 ## Сценарії використання
 
-- `llm-lib/tests/acp.test.mjs` (runAcpAgent; getAcpPresets (smoke через реально збудований napi-аддон)) — делегує kind/prompt/cwd у native.oneShotAcp і віддає його результат; без опцій (старий виклик без 4-го аргументу) — tier не заданий; tier прокидається в native.oneShotAcp четвертим аргументом; kind
+- `llm-lib/tests/acp.test.mjs` (runAcpAgent; getAcpPresets (smoke через реально збудований napi-аддон)) — interactive mode делегує kind/prompt/cwd у native.oneShotAcp і віддає його результат; без tier або interactive mode — fail-closed; tier прокидається в native.oneShotAcp четвертим аргументом; kind
 
 ## Гарантії поведінки
 

package/lib/docs/agent-skill.md

@@ -3,33 +3,31 @@ type: JS Module
 title: agent-skill.mjs
 resource: llm-lib/lib/agent-skill.mjs
 docgen:
-  crc: b7312bad
+  crc: 7c86fb8b
   model: openai-codex/gpt-5.4-mini
   tier: cloud-min
   score: 100
-  issues: judge:error
+  issues: judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Організовує один запуск skill і керує його виконанням у межах поточного контексту, щоб агент отримував потрібний стан для роботи. Має локальні fail-safe гілки для контрольованих збоїв; інші помилки можуть поширюватися назовні.
+Файл запускає один агентський skill-run і передає виконання в існуючу сесію, щоб пов’язати його з обраним tier або modelSpec та зберегти трасування контексту. Це потрібно, щоб виклик або завершився успішно, або повернув діагностовану помилку; частина fail-safe гілок обробляється локально, а інші помилки можуть поширюватися назовні.
 
 ## Поведінка
 
-1. Приймає готовий prompt для одного skill-запуску та фіксує контекст виконання: skill, tier, modelSpec, cwd, timeout, maxTokens, caller і chain.
-2. Переходить у наступний крок chain, якщо ланцюжок передано, і готує кореляцію для подальшого обліку.
-3. Обирає модель через registry; якщо модель явно задана, але не знаходиться, завершує запуск без виконання skill.
-4. Створює pi-сесію з повним набором built-in tools, включно з bash, і прив’язує до неї поточний working directory та рівень thinking.
-5. Для локальних моделей додає chain-кореляцію; для інших моделей цього не робить.
-6. Запускає один skill-цикл і стрімить текст відповіді в stdout у міру надходження.
-7. Рахує turns і tool calls; якщо turns перевищують аварійну стелю, зупиняє виконання як runaway-backstop.
-8. Обмежує час виконання; при timeout перериває сесію.
-9. Якщо модель або registry недоступні, повертає fail-safe результат із помилкою без продовження прогону.
-10. Якщо під час prompt виникає memory-guard rejection для локального model-сервера, завершує як fail-fast і не маскує помилку.
-11. Після завершення формує telemetry з фактичним model, turns, tool calls, backstop-станом і тривалістю.
-12. Передає результат у chain і trace, а також зберігає capture для подальшого аналізу прогону.
-13. Повертає ознаку успіху, telemetry і текст помилки; успіх можливий лише коли немає помилки й не спрацював backstop.
+1. Приймає готовий prompt для одного skill-run і фіксує контекст виконання: skill, tier, modelSpec, cwd, thinkingLevel, timeout, maxTokens, caller та chain.
+2. Перемикає ланцюжок на наступний крок, якщо chain передано, і готує контрольну позначку для трасування запиту.
+3. Перевіряє, чи задано спосіб вибору моделі: або tier, або явний modelSpec. Якщо ні — завершує невдачею без запуску сесії.
+4. Визначає цільову модель і перевіряє, чи вона доступна в registry. Якщо модель не знайдена або registry недоступний — завершує невдачею з діагностикою.
+5. Створює агентську сесію з повним набором вбудованих tools і без write-guard; для локальних моделей може підключити chain-кореляцію, для інших — ні.
+6. Підписується на події сесії, щоб рахувати turns і tool-виклики, стрімити текст відповіді у stdout та зберегти підсумкове usage з фінального повідомлення.
+7. Запускає виконання prompt із пер-call timeout і runaway-backstop на turns. Якщо ліміт turns перевищено або спрацьовує timeout, сесію зупиняє.
+8. Якщо під час запуску виникає memory-guard rejection для локального model-сервера, повертає failure-поведінку з друком prompt і помилкою замість structured result.
+9. Після завершення формує підсумок виконання: фактичну модель, кількість turns, кількість tool-викликів, факт спрацювання backstop і тривалість.
+10. Оновлює chain і trace, а також зберігає capture-дані для подальшого аналізу: prompt, output, usage, error і кореляційні поля.
+11. Повертає успіх лише тоді, коли немає помилки і не спрацював backstop; інакше повертає невдачу з telemetry, де це можливо.
 
 ## Публічний API
 
@@ -37,7 +35,7 @@ docgen:
 
 ## Сценарії використання
 
-- `llm-lib/tests/agent-skill.test.mjs` (runAgentSkill) — happy-path: ok, телеметрія, стрім тексту, trace kind:; createSession отримує тиру → thinkingLevel і cwd; maxTokens прокидається у createSession (0 = без стелі); з chain: step/note/chain-поля у trace; хмарна модель → chain:null у сесію; modelSpec порожній: telemetry.model — фактично резолвлена pi-модель, не echo spec; ще 5
+- `llm-lib/tests/agent-skill.test.mjs` (runAgentSkill) — happy-path: ok, телеметрія, стрім тексту, trace kind:; createSession отримує тиру → thinkingLevel і cwd; maxTokens прокидається у createSession (0 = без стелі); з chain: step/note/chain-поля у trace; хмарна модель → chain:null у сесію; явний modelSpec зберігається у telemetry; ще 5
 
 ## Гарантії поведінки
 

package/lib/docs/batch.md

@@ -3,31 +3,43 @@ type: JS Module
 title: batch.mjs
 resource: llm-lib/lib/batch.mjs
 docgen:
-  crc: 10b603cc
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
-  score: 80
+  crc: ce0ba158
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Тип 2b (OpenAI-сумісний API, batch) — **лише емуляція** у v1 (рішення Р,
-задача T6): чанкований конкурентний прогін через Тип 2a
-(`llm_lib::local_cloud`) під інтерфейсом `submit → progress → results` —
-той самий інтерфейс, яким говорив би й справжній OpenAI Batch API
-(`/v1/batches`, v2), якому локальний omlx (перший споживач) не має.
+Тип 2b (OpenAI-сумісний API, batch) — `submitBatch` обирає між клієнтською
+емуляцією (v1, чанкований конкурентний прогін через Тип 2a
+`llm_lib::local_cloud`) і справжнім `/v1/batches` litellm batch-adapter-а
+(спека `docs/specs/2026-07-27-batch-local-avg-real-batches.md`), під тим
+самим інтерфейсом `submit → progress → results` для обох. Вибір —
+`backend` (дефолт `'auto'`: реальний Batch API лише коли резолвлений
+провайдер `litellm` і кешована мережева проба адаптера пройшла; локальний
+omlx завжди йде емуляцією).
 
-Тонкий JS-клієнт до Rust-крейта `llm_lib::batch` через napi FFI
-in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного чанкінгу
-тут (анти-приклад, якого це узагальнює: `mlmail/use-summary.js` чанкує
-переклади проти omlx вручну, з вистражданими лімітами).
+Тонкий JS-клієнт до Rust-крейта `llm_lib::batch`/`llm_lib::remote_batch`
+через napi FFI in-process (`llm-lib/crates/llm-lib-napi`) — жодного
+власного чанкінгу чи HTTP тут (анти-приклад, якого це узагальнює:
+`mlmail/use-summary.js` чанкує переклади проти omlx вручну, з
+вистражданими лімітами).
+
+## Поведінка
+
+submitBatch працює з набором batch-елементів як з одним запитом: для кожного елемента зберігається зв’язок між `customId` і відповіддю, а порядок результатів відповідає порядку вхідних `items`.
+
+Якщо для елемента є помилка, у результаті повертається запис з `error` замість `ok`; для одного елемента заповнюється рівно одне з цих полів. Це дає змогу обробляти частково успішні batch-и без втрати прив’язки до конкретного `customId`.
+
+Передані `system`, `localProviders`, `backend`, `chunkSize`, `concurrency`, `pollIntervalMs` і `pollTimeoutMs` впливають на поведінку batch-виклику, а `onProgress` дозволяє отримувати проміжний стан виконання.
 
 ## Публічний API
 
-- submitBatch — Емуляція batch-виклику Типу 2b. `modelSpecOrTier` — той самий контракт,
-що й у [`oneShotLocalCloud`] з `local-cloud.mjs`: явний
-`"provider/model-id"` або абстрактний тир (`min`/`avg`/`max`).
+- submitBatch — Batch-виклик Типу 2b. `modelSpecOrTier` — той самий контракт, що й у
+[`oneShotLocalCloud`] з `local-cloud.mjs`: явний `"provider/model-id"`
+абстрактний тир (`min`/`avg`/`max`) або явний env-selector.
 
 ## Сценарії використання
 

package/lib/docs/local-cloud.md

@@ -3,32 +3,35 @@ type: JS Module
 title: local-cloud.mjs
 resource: llm-lib/lib/local-cloud.mjs
 docgen:
-  crc: fc09aee2
+  crc: cedae6fe
   model: openai-codex/gpt-5.5
   tier: cloud-avg
-  score: 100
+  score: 80
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Надає Node-доступ до одного OpenAI-сумісного запиту `chat/completions` для локального або хмарного провайдера через спільний Rust-шар. `oneShotLocalCloud` існує як тонкий JS-вхід до `llm_lib::local_cloud` через `napi FFI in-process` у `llm-lib/crates/llm-lib-napi`, щоб визначення моделей, конфігурація локальних провайдерів і HTTP-взаємодія залишалися в єдиній реалізації без окремого клієнта в JS і без агентського циклу.
+Тип 2a (OpenAI-сумісний API, sync) для Node — прямий HTTP до OpenAI-compatible
+ендпоінта (`chat/completions`): локальні провайдери (напр. omlx) і хмарні
+(стандартна автентифікація провайдера) — без агентського циклу.
 
-## Поведінка
-
-1. `oneShotLocalCloud` приймає запит на один OpenAI-сумісний chat-виклик для локального або хмарного провайдера без агентського циклу.
-2. Визначає цільову модель як явну специфікацію провайдера або як абстрактний тир, щоб використовувати спільне правило резолву моделей із Rust-шару.
-3. Передає текст користувача, optional system-повідомлення та конфігурацію локальних провайдерів до in-process Rust-клієнта через napi FFI.
-4. Делегує HTTP-взаємодію з OpenAI-compatible ендпоінтом Rust-реалізації, щоб у JS-шарі не виникало окремого клієнта й розрізненого читання `settings.json`.
-5. Повертає текст відповіді моделі як результат одного синхронного за сценарієм запиту.
+Тонкий JS-клієнт до Rust-крейта `llm_lib::local_cloud` через napi FFI
+in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного HTTP-клієнта
+тут (анти-приклад, якого це уникає: `mlmail` читає `~/.omlx/settings.json`
+і б'є в ендпоінт напряму замість спільної точки, задача T5/рішення Н).
 
 ## Публічний API
 
-- oneShotLocalCloud — Один chat-виклик Типу 2a. `modelSpecOrTier` — або явний `"provider/model-id"`,
-або абстрактний тир (`min`/`avg`/`max`, рішення К), що резолвиться в Rust
+- oneShotLocalCloud — Один chat-виклик Типу 2a. `modelSpecOrTier` — явний `"provider/model-id"`,
+абстрактний tier або `N_LOCAL_*_MODEL`/`N_CLOUD_*_MODEL` selector
 через ту саму [`llm_lib::resolve_model`], що й `resolveModel` з
 `model-tiers.mjs`.
 
+## Сценарії використання
+
+- `llm-lib/tests/local-cloud.test.mjs` (oneShotLocalCloud) — делегує modelSpecOrTier/prompt у native.oneShotLocalCloud і віддає його результат; явний; localProviders і system прокидаються в options; без опцій (лише modelSpecOrTier/prompt) — localProviders/system undefined
+
 ## Гарантії поведінки
 
 - Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/docs/local-providers.md

@@ -3,26 +3,36 @@ type: JS Module
 title: local-providers.mjs
 resource: llm-lib/lib/local-providers.mjs
 docgen:
-  crc: 6513b04f
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
+  crc: cd7b4cfa
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Дефолтна мапа local-провайдерів для `llm_lib::local_cloud` у форматі `{ prefix: { baseUrl, apiKey } }`, яку споживають `oneShotLocalCloud` і `submitBatch`.
-
-`omlx` і `litellm` завжди присутні в мапі одночасно, а фактичний виклик іде рівно в один клієнт за `provider`-префіксом у model-spec. Якщо spec не вказує на певний префікс, відповідний запис у мапі не отримує запиту.
+Файл надає стандартну мапу local-провайдерів для `llm_lib::local_cloud` у формі `{ prefix: { baseUrl, apiKey } }`, щоб JS-частина могла передати Rust-крейту готові endpoints для `oneShotLocalCloud` і `submitBatch`. `defaultLocalProviders` завжди описує `omlx` і `litellm` одночасно, а фактичний мережевий запит отримує лише провайдер, чий префікс вибрано в model-spec, наприклад `N_LOCAL_MIN_MODEL`.
 
 ## Поведінка
 
-1. `defaultLocalProviders` формує єдиний дефолтний набір local-провайдерів для `llm_lib::local_cloud`, щоб обидва зареєстровані напрямки — `omlx` і `litellm` — були доступні одночасно в очікуваному `{ prefix: { baseUrl, apiKey } }` форматі для `oneShotLocalCloud` і `submitBatch`.
-2. Для `omlx` функція бере `baseUrl` з `N_OMLX_BASE_URL`, а якщо його немає — підставляє `http://127.0.0.1:8000/v1/`; `apiKey` бере з `N_OMLX_API_KEY`, інакше лишає порожнім значенням.
-3. Для `litellm` функція бере `baseUrl` з `N_LITELLM_BASE_URL`, а якщо його немає — підставляє `https://llm.7n.ai/v1/`; `apiKey` бере з `N_LITELLM_API_KEY`, інакше лишає порожнім значенням.
-4. Функція не вирішує, який провайдер “активний” сама по собі: вибір фактично визначається тим, який provider-префікс вказаний у model-spec на кшталт `N_LOCAL_MIN_MODEL`.
-5. Коли model-spec вказує на один префікс, `LocalCloud::one_shot_with_spec` звертається рівно до відповідного клієнта; другий запис у мапі залишається запасним і не отримує запитів, доки жоден spec на нього не посилається.
+1. `defaultLocalProviders` формує стандартний набір local-провайдерів для `llm_lib::local_cloud`, щоб JS-частина передавала Rust-крейту готову мапу endpoint-ів у спільному форматі.
+
+2. До мапи завжди входять `omlx` і `litellm`; наявність обох записів не означає одночасне використання обох провайдерів.
+
+3. Активним стає лише провайдер, чий префікс вибрано в model-spec, тому запит спрямовується до одного відповідного клієнта.
+
+4. Для `omlx` використовується локальна адреса за замовчуванням `http://127.0.0.1:8000/v1/`, щоб підтримати локальний LLM-сервер без обов’язкової конфігурації.
+
+5. Для `litellm` використовується віддалена адреса за замовчуванням `https://llm.7n.ai/v1/`, щоб мати готовий fallback-провайдер для централізованого LLM endpoint-а.
+
+6. Значення адрес і ключів доступу можуть надходити з оточення, щоб одна й та сама логіка працювала в локальному, CI та production-середовищах без зміни коду.
+
+7. Файл лише збирає конфігурацію провайдерів і не виконує власних операцій запису.
+
+## Сценарії використання
+
+- `llm-lib/tests/local-providers.test.mjs` (defaultLocalProviders) — без env — дефолтні baseUrl для omlx і litellm, apiKey null; обидва провайдери завжди присутні одночасно (жоден не вимикається іншим); N_OMLX_BASE_URL/N_OMLX_API_KEY перекривають дефолт omlx; N_LITELLM_BASE_URL/N_LITELLM_API_KEY перекривають дефолт litellm
 
 ## Гарантії поведінки
 

package/lib/docs/model-tiers.md

@@ -3,27 +3,21 @@ type: JS Module
 title: model-tiers.mjs
 resource: llm-lib/lib/model-tiers.mjs
 docgen:
-  crc: 05c5eb6a
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
+  crc: 1953f7a9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
   score: 100
-  issues: judge-refine:kept-original,judge:inaccurate:0.97
+  issues: judge:error
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-`LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX`, `CLOUD_MIN`, `CLOUD_AVG` і `CLOUD_MAX` задають спільні варіанти модельного рівня для локального та хмарного сценаріїв, щоб споживачі використовували однакові значення для вибору режиму роботи. `parseModelId` і `formatModelSpec` узгоджують подання модельного ідентифікатора між внутрішнім представленням і зовнішнім форматом, а `resolveModel` повертає уже погоджений варіант для подальшого використання. `thinkingLevelForTier` фіксує відповідність між tier і рівнем thinking, а `isLocalModel` дає змогу відрізнити локальні моделі від інших без дублювання цієї перевірки в різних місцях.
+Файл відповідає за визначення та вибір моделі для виконання завдань. Він інтерпретує граничні значення, такі як `LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX` для локальних моделей та `CLOUD_MIN`, `CLOUD_AVG`, `CLOUD_MAX` для хмарних моделей. На основі цих значень відбувається пошук відповідної моделі через функцію `resolveModel`. Після вибору моделі, відповідно до її типу, визначається відповідний рівень обробки за допомогою `thinkingLevelForTier`.
 
 ## Поведінка
 
-LOCAL_MIN, LOCAL_AVG, LOCAL_MAX, CLOUD_MIN, CLOUD_AVG і CLOUD_MAX беруть значення з environment на старті модуля та задають єдину політику вибору моделі для локального й хмарного шарів. Ці значення далі слугують опорою для resolveModel, який повертає вже фактично обраний model spec у форматі provider/model-id або порожній рядок, якщо дефолт провайдера лишився substrate-рівню. Невідомий tier відсіюється на цьому рівні як помилка контракту.
-
-thinkingLevelForTier переводить rung-tier у дискретний рівень thinking, щоб downstream-логіка могла узгоджено трактувати силу моделі без повторного аналізу spec. local-min і local-min-retry зводяться до найнижчого рівня, cloud-min, cloud-avg і cloud-max піднімають рівень відповідно до потужності хмарного вибору.
-
-parseModelId і formatModelSpec утворюють парний обмін між рядковим model spec та об’єктом моделі: перший розбирає канонічний рядок на provider та id, другий збирає фактично резолвлену модель назад у той самий формат. Якщо spec або модель неповні, результатом є null, щоб не маскувати malformed або відсутній стан.
-
-isLocalModel використовує ту саму політику, що й resolveModel: спочатку звіряє явні локальні тири, а потім визначає локальність за provider із model spec. Це дає спільне правило для агрегатів local/cloud і для рішень, де потрібно відрізнити локальний шлях від хмарного без дублювання логіки в consumers.
+Значення `LOCAL_MIN`, `LOCAL_AVG`, `LOCAL_MAX`, `CLOUD_MIN`, `CLOUD_AVG`, `CLOUD_MAX` визначаються через змінні середовища, використовуючи префікси, які можуть бути налаштовані для вказівки на конкретні моделі. Ці значення слугують стартовими точками для визначення моделі та її рівні у ланцюжку. Коли викликається `resolveModel` з певною стартовою сходинкою, ця сходинка використовується для каскадного пошуку моделі, починаючи з локальних мінімальних та переходячи до хмарних, якщо необхідна модель не знайдена локально. Результат `resolveModel` повертає ідентифікатор моделі у форматі `"provider/model-id"`. Цей ідентифікатор може бути перетворений на пару `provider` та `id` за допомогою `parseModelId` або знову відформатований назад у `"provider/model-id"` за допомогою `formatModelSpec`, що корисно при отриманні дефолтної моделі від системи. `isLocalModel` приймає специфікатор моделі та визначає, чи належить вона до локальних моделей, спираючись на визначені стартові тири або на налаштування провайдерів у змінній середовища. Якщо ідентифікатор моделі відомий, `thinkingLevelForTier` визначає відповідний рівень складності (від `low` до `xhigh`) на основі того, який із визначених тирів був обраний.
 
 ## Публічний API
 
@@ -33,14 +27,12 @@ isLocalModel використовує ту саму політику, що й re
 - CLOUD_MIN — Мінімальний хмарний (потрібен ключ у pi auth). Напр.: openai/gpt-5.4-mini
 - CLOUD_AVG — Середній хмарний. Напр.: openai/gpt-5.4
 - CLOUD_MAX — Максимальний хмарний. Напр.: openai/gpt-5.5
-- resolveModel — Каскадне розв'язання абстрактного тиру в `"provider/model-id"` —
-napi-делегація в `llm_lib::resolve_model` (задача T5, рішення Е): та сама
-логіка, що й Rust-каскад у `tiers.rs`:
-  'min' → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
-  'avg' → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
-  'max' → LOCAL_MAX → CLOUD_MAX
-Тир валідується тут (не в Rust) — щоб зберегти контракт `TypeError` для
-невідомого тиру без потреби мапити помилку з napi-боку.
+- resolveModel — Універсально резолвить модель від явної env-сходинки:
+- LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN → CLOUD_AVG → CLOUD_MAX;
+- LOCAL_AVG → LOCAL_MAX → CLOUD_AVG → CLOUD_MAX;
+- LOCAL_MAX → CLOUD_MAX;
+- cloud-старти проходять лише відповідну й сильніші cloud-сходинки.
+`min`/`avg`/`max` лишаються alias-ами відповідних `N_LOCAL_*_MODEL`.
 - thinkingLevelForTier — `thinkingLevel` за rung-тиром fix-драбини: слабка локальна — `low`,
 cloud-min — `medium`, cloud-avg — `high`, cloud-max (experiment-only tier,
 не в production ladder) — `xhigh`.
@@ -60,7 +52,7 @@ model-spec, не за наявністю запису в мапі. Викори
 
 ## Сценарії використання
 
-- `llm-lib/tests/model-tiers.test.mjs` (isLocalModel; parseModelId) — omlx-провайдер — локальний (дефолт N_LLM_LOCAL_PROVIDERS); litellm-провайдер — теж локальний за дефолтом (перемикач omlx/litellm через тир-env); порожній/malformed spec — не локальний; кастомний список провайдерів через env (ізольований re-import); звичайна пара; ще 8
+- `llm-lib/tests/model-tiers.test.mjs` (isLocalModel; parseModelId) — omlx-провайдер — локальний (дефолт N_LLM_LOCAL_PROVIDERS); litellm-провайдер — теж локальний за дефолтом (перемикач omlx/litellm через тир-env); порожній/malformed spec — не локальний; кастомний список провайдерів через env (ізольований re-import); звичайна пара; ще 9
 
 ## Гарантії поведінки
 

package/lib/docs/one-shot.md

@@ -3,32 +3,37 @@ type: JS Module
 title: one-shot.mjs
 resource: llm-lib/lib/one-shot.mjs
 docgen:
-  crc: 3b62f8db
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 38adb9ce
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Цей механізм виконує одноразовий запит до мовної моделі (LLM) через публічну функцію `runOneShot`. Він збирає необхідну інформацію, ініціює взаємодію та консолідує вхідні дані у єдиний текстовий запит. Функція завжди перехоплює помилки (fail-safe) та не кидає винятків назовні. У разі успішного отримання відповіді від LLM, що є операцією лише для читання (read-only), повертається згенерований текст, дані про використання моделі та метадані.
+`runOneShot` виконує одноразовий запит до вибраної моделі чи tier без agent-циклу і використовується як точка входу для сценаріїв, де потрібна одна відповідь без подальшої взаємодії. У файлі є локальні fail-safe гілки для окремих збоїв.
 
 ## Поведінка
 
-Поведінка:
-
-1. Для виконання одноразового LLM-виклику спочатку збирається необхідна інформація для доступу до моделі, використовуючи надані рівні моделі.
-2. Після визначення моделі створюється сесія для взаємодії з LLM, використовуючи налаштування, які гарантують виконання завдання без використання інструментів.
-3. Всі вхідні повідомлення об'єднуються в єдиний текстовий запит.
-4. Система чекає відповіді від LLM, обмеженої заданим часовим лімітом.
-5. Під час очікування відбувається збір генерованого тексту та метаданих об'єднання (usage) відповіді.
-6. У разі будь-якої помилки під час пошуку моделі, створення сесії чи самого виклику, виклик завершується з повідомленням про помилку.
-7. У разі успіху, функція повертає згенерований текст, інформацію про використання моделі, статус помилки та метадані моделі, використовуючи інформацію, зібрану під час взаємодії з сесією.
+1. Приймає набір повідомлень, зводить їх в один запит і рахує його відбиток для подальшого трасування.
+2. Визначає модель виконання: або за явним spec, або за tier; якщо вибір не задано, повертає контрольовану помилку без запуску запиту.
+3. Перевіряє, чи існує запитана модель; якщо ні — завершує виклик керованою помилкою.
+4. Ініціює одноразову сесію без інструментів, щоб отримати plain completion без agent-циклу.
+5. Відправляє запит із лімітом часу; якщо під час виконання виникає memory-guard відмова локального model-сервера, пробиває її назовні як fail-fast сценарій.
+6. Акумулює текст відповіді та службову інформацію про завершення; якщо відповідь обрізана стелею, це фіксується у stop reason для рішення колером.
+7. Після завершення повертає очищений текст відповіді, usage, помилку за потреби, фактичну модель, stop reason і caller.
+8. Додатково пише trace і capture для спостережуваності, але не гарантує обробку всіх зовнішніх помилок.
 
 ## Публічний API
 
-- runOneShot — виконує обмежений LLM-виклик одноразово; опція `maxTokens` задає per-call стелю відповіді (undefined → дефолт пакета, 0 → без стелі); у результаті додатково повертається `stopReason` (`'length'` = відповідь обрізана стелею — політика повтору за колером).
-- MEMORY_ERROR_RE — публічна частина fail-fast error-контракту: regex для класифікації memory-guard помилки локального model-сервера (пробити нагору й завершити процес, а не ковтати як per-item помилку).
+- runOneShot — Виконує bounded one-shot LLM-виклик.
+
+## Сценарії використання
+
+- `llm-lib/tests/one-shot.test.mjs` (runOneShot) — happy path: збирає текст + usage; усі messages (system+user) зливаються в один prompt; без replaceInstructions; модель не знайдена → error, сесія не створюється; prompt кидає → error; timeout → error; ще 13
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe); виняток — memory-guard rejection, який свідомо кидає Error після друку тіла запиту.
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Містить локальні fail-safe гілки.

package/lib/local-cloud.mjs

@@ -11,11 +11,11 @@
 import { loadNative } from './internal/native.mjs'
 
 /**
- * Один chat-виклик Типу 2a. `modelSpecOrTier` — або явний `"provider/model-id"`,
- * або абстрактний тир (`min`/`avg`/`max`, рішення К), що резолвиться в Rust
+ * Один chat-виклик Типу 2a. `modelSpecOrTier` — явний `"provider/model-id"`,
+ * абстрактний tier або `N_LOCAL_*_MODEL`/`N_CLOUD_*_MODEL` selector
  * через ту саму [`llm_lib::resolve_model`], що й `resolveModel` з
  * `model-tiers.mjs`.
- * @param {string} modelSpecOrTier `"provider/model-id"` або `'min'|'avg'|'max'`
+ * @param {string} modelSpecOrTier `"provider/model-id"`, tier або env-selector
  * @param {string} prompt user-репліка
  * @param {{
  *   localProviders?: Record<string, { baseUrl: string, apiKey?: string | null }>,

package/lib/model-tiers.mjs

@@ -34,29 +34,40 @@ export const CLOUD_AVG = env.N_CLOUD_AVG_MODEL ?? ''
 /** Максимальний хмарний. Напр.: openai/gpt-5.5 */
 export const CLOUD_MAX = env.N_CLOUD_MAX_MODEL ?? ''
 
-/** Валідні тири — та сама множина, що й `parse_tier` у napi-крейті. */
-const KNOWN_TIERS = new Set(['min', 'avg', 'max'])
+/** Абстрактний tier → явна стартова env-сходинка. */
+const TIER_START = {
+  min: 'N_LOCAL_MIN_MODEL',
+  avg: 'N_LOCAL_AVG_MODEL',
+  max: 'N_LOCAL_MAX_MODEL'
+}
+const MODEL_ENV_KEYS = new Set([
+  'N_LOCAL_MIN_MODEL',
+  'N_LOCAL_AVG_MODEL',
+  'N_LOCAL_MAX_MODEL',
+  'N_CLOUD_MIN_MODEL',
+  'N_CLOUD_AVG_MODEL',
+  'N_CLOUD_MAX_MODEL'
+])
 
 /**
- * Каскадне розв'язання абстрактного тиру в `"provider/model-id"` —
- * napi-делегація в `llm_lib::resolve_model` (задача T5, рішення Е): та сама
- * логіка, що й Rust-каскад у `tiers.rs`:
- *   'min' → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
- *   'avg' → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
- *   'max' → LOCAL_MAX → CLOUD_MAX
- * Тир валідується тут (не в Rust) — щоб зберегти контракт `TypeError` для
- * невідомого тиру без потреби мапити помилку з napi-боку.
- * @param {'min'|'avg'|'max'} tier тир
- * @param {{ native?: { resolveModel: (tier: string) => string | null } }} [deps] інжект `native` для тестів
+ * Універсально резолвить модель від явної env-сходинки:
+ * - LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN → CLOUD_AVG → CLOUD_MAX;
+ * - LOCAL_AVG → LOCAL_MAX → CLOUD_AVG → CLOUD_MAX;
+ * - LOCAL_MAX → CLOUD_MAX;
+ * - cloud-старти проходять лише відповідну й сильніші cloud-сходинки.
+ * `min`/`avg`/`max` лишаються alias-ами відповідних `N_LOCAL_*_MODEL`.
+ * @param {'min'|'avg'|'max'|'N_LOCAL_MIN_MODEL'|'N_LOCAL_AVG_MODEL'|'N_LOCAL_MAX_MODEL'|'N_CLOUD_MIN_MODEL'|'N_CLOUD_AVG_MODEL'|'N_CLOUD_MAX_MODEL'} requested стартова сходинка
+ * @param {{ native?: { resolveModel: (start: string) => string | null } }} [deps] інжект `native` для тестів
  * @returns {string} `"provider/model-id"` або `''` (дефолт провайдера substrate)
  * @throws {TypeError} якщо tier невідомий
  */
-export function resolveModel(tier, deps = {}) {
-  if (!KNOWN_TIERS.has(tier)) {
-    throw new TypeError(`resolveModel: unknown tier "${tier}". Use 'min', 'avg', or 'max'.`)
+export function resolveModel(requested, deps = {}) {
+  const start = TIER_START[requested] ?? requested
+  if (!MODEL_ENV_KEYS.has(start)) {
+    throw new TypeError(`resolveModel: unknown model selector ${JSON.stringify(requested)}.`)
   }
   const native = deps.native ?? loadNative()
-  return native.resolveModel(tier) ?? ''
+  return native.resolveModel(start) ?? ''
 }
 
 // ── Escalation-rung → thinkingLevel ──────────────────────────────────────────

package/lib/one-shot.mjs

@@ -81,7 +81,7 @@ async function defaultCreateSession({ registry, model, cwd, thinkingLevel, maxTo
  */
 export async function runOneShot({
   messages,
-  modelTier = 'min',
+  modelTier,
   modelSpec,
   thinkingLevel,
   timeoutMs = DEFAULT_TIMEOUT_MS,
@@ -122,7 +122,8 @@ export async function runOneShot({
   let model
   try {
     registry = deps.registry ?? (await getReg())
-    spec = modelSpec ?? resolveModel(modelTier)
+    if (!modelSpec && !modelTier) return fail('model selection: передай modelTier або явний modelSpec', null)
+    spec = modelSpec || resolveModel(modelTier)
     model = spec ? resolveModelSpec(registry, spec) : null
     if (spec && !model) return fail(`модель не знайдена: ${spec}`, spec)
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.13.0",
+  "version": "2.13.2",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",
@@ -56,8 +56,8 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@7n/llm-lib-darwin-arm64": "2.9.7",
-    "@7n/llm-lib-linux-x64": "2.9.7"
+    "@7n/llm-lib-darwin-arm64": "2.13.2",
+    "@7n/llm-lib-linux-x64": "2.13.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "~0.80.10",