@7n/llm-lib 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.12.0] - 2026-07-28
+
+### Changed
+
+- llm-lib v0.2.3: pi-тіри переглянуто (рішення З.1) — min/avg тепер локальні моделі (omlx/gemma-4-e4b-it-OptiQ-4bit, litellm/gemma-4-26b-awq через llm.7n.ai), max лишається openai-codex/gpt-5.6-sol; передумова — провайдери omlx/litellm у pi models.json
+- release: @7n/llm-lib@2.10.1, @7n/rules@1.52.1, @7n/rules-lang-js@0.23.1
+- Механічно додано change-файл для поточних змін у workspace.
+
 ## [2.11.0] - 2026-07-27
 
 ### Added

package/lib/docs/acp.md

@@ -3,24 +3,27 @@ type: JS Module
 title: acp.mjs
 resource: llm-lib/lib/acp.mjs
 docgen:
-  crc: 587f1966
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
-  score: 100
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: 1ed416a1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 80
 ---
 
 ## Огляд
 
-Публічна точка входу `runAcpAgent` для запуску ACP-агента `cursor`, `codex` або `pi` через локально залогінений CLI без API-ключа. Це тонкий JS-міст до `llm_lib::acp` у `llm-lib/crates/llm-lib-napi`, без власної ACP JSON-RPC чи `ClientSideConnection` логіки; протокольна поведінка, `session/prompt`, `session/request_permission`, `tier→env/args/post-session-config` resolving і watchdog на мертвий або незапущений дочірній процес зосереджені в Rust. `AcpAgentKind` охоплює лише `cursor`/`codex`/`pi`; `claude` тут відсутній, а deprecated `claude`-runner лишається окремим JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
+ACP (Agent Client Protocol, Zed) — доступ до `cursor`/`codex`/`pi` через
+особисту підписку (вже залогінений локально CLI), не API-ключ.
 
-## Поведінка
+Тонкий JS-клієнт до Rust-крейта `llm_lib::acp` через napi FFI
+in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного
+ACP JSON-RPC/`ClientSideConnection` тут; уся протокольна логіка (спавн
+агента, `session/prompt`, автоапрув `session/request_permission`,
+тір→env/args/post-session-config резолвінг) живе в Rust, разом з
+watchdog-поведінкою на мертвий/незапущений дочірній процес.
 
-1. `runAcpAgent` запускає один запит до ACP-агента з особистою підпискою для `cursor`, `codex` або `pi` у межах поточного робочого каталогу.
-2. Якщо задано `tier`, передає цю абстракцію в нативний шар, щоб далі саме Rust визначив відповідні параметри сесії для вибраного агента.
-3. Якщо `tier` не задано, використовує стандартну поведінку персонально залогіненого CLI без окремого вибору рівня.
-4. Для виконання звертається до нативної реалізації в процесі, яка вже містить протокольну логіку, запуск сесії та обробку дозволів; цей файл не реалізує власний ACP-обмін і не працює з `claude`.
-5. Повертає повний текст відповіді агента після завершення одного ходу.
+`claude` тут немає — Rust-крейт моделює лише `cursor`/`codex`/`pi`
+(`AcpAgentKind`); deprecated `claude`-раннер лишається окремим
+JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
 
 ## Публічний API
 
@@ -30,6 +33,10 @@ Rust сам резолвить tier→env/args/post-session-config з пресе
 (`one_shot_acp_with_tier`) — жодного JS-хелпера "пресет→env" тут немає.
 Без `tier` — стара поведінка (модель = персональний конфіг CLI на машині).
 
+## Сценарії використання
+
+- `llm-lib/tests/acp.test.mjs` (runAcpAgent; getAcpPresets (smoke через реально збудований napi-аддон)) — делегує kind/prompt/cwd у native.oneShotAcp і віддає його результат; без опцій (старий виклик без 4-го аргументу) — tier не заданий; tier прокидається в native.oneShotAcp четвертим аргументом; kind
+
 ## Гарантії поведінки
 
 - Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/lib/docs/agent-fix.md

@@ -3,25 +3,29 @@ type: JS Module
 title: agent-fix.mjs
 resource: llm-lib/lib/agent-fix.mjs
 docgen:
-  crc: 6a36d9a0
+  crc: 0babfe80
   model: openai-codex/gpt-5.4-mini
   tier: cloud-min
   score: 100
-  issues: judge-refine:kept-original,judge:inaccurate:0.98
+  issues: judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Модуль формує два промпти для локального виправлення порушення за правилом: `buildVerifyFeedbackPrompt` збирає запит на перевірку вже виявленого зворотного зв’язку, а `buildFixPrompt` — запит на виправлення з урахуванням обмеженого контексту й дозволених файлів. `runAgentFix` запускає цей цикл і повертає результат без пробросу помилок назовні: будь-які збої перехоплюються, щоб процес залишався fail-safe.
+Файл керує автоматизованим виправленням порушень через `buildVerifyFeedbackPrompt`, `buildFixPrompt` і `runAgentFix`: він формує запит на перевірку, готує запит на виправлення та запускає агентне виправлення. Локальні fail-safe гілки дозволяють безпечно обробляти окремі збої, тоді як інші помилки можуть поширюватися назовні.
 
 ## Поведінка
 
-Спочатку формується fix-промпт із правилом, порушенням і доступним контекстом редагування; для generic-режиму він жорстко звужує простір змін до дозволених файлів, а для test-generation розділяє read-only джерела й тестові файли. Якщо попередня перевірка вже дала зворотний зв’язок, він додається в той самий промпт як додаткове обмеження. Далі виконується одна агентна спроба виправлення в межах рунга: результатом стає набір торкнутих файлів, телеметрія або помилка, а при падінні повертається rollback без винесення винятку назовні.
+Потік починається з `runAgentFix`: вона збирає контекст правила, порушення, цільові файли, режим редагування та зовнішні залежності, будує fix-промпт і запускає одну рунґ-спробу з обмеженням часу. У цьому промпті одразу фіксуються межі допустимих змін: агент має працювати лише в межах дозволеного контексту й не підміняти перевірку семантичними «виправленнями» поза реальною правкою коду.
 
-Після внесення змін запускається verify-петля над тими самими торкнутими файлами. Вона повторює canonical verify у тій самій сесії, а при невдалому результаті передає точний вивід перевірки назад у verify-feedback prompt і продовжує, доки не буде ok, не вичерпається ліміт спроб або не закінчиться спільний таймаут рунга. Якщо сама перевірка падає інфраструктурно, це не маскується під звичайне порушення: петля зупиняється чесною помилкою. Зовнішній consumer лишається джерелом правди про остаточне re-detect, а тут використовується лише рання локальна корекція.
+Після редагування `runAgentFix` передає керування verify-петлі. Та повторно перевіряє результат через canonical verify і, якщо помилки лишилися, формує для тієї ж сесії feedback через `buildVerifyFeedbackPrompt`. Далі цикл триває лише в межах того самого часового бюджету, доки не буде досягнуто успіху або вичерпано ліміт спроб. Якщо сама перевірка ламається як інфраструктурна подія, це не маскується під звичайне порушення.
 
-Увесь потік працює fail-safe: помилки не пробиваються назовні як винятки, а повертаються у результаті як error. Загальний стан між етапами — це лише дані рунга: ruleId, violation, контекст правил, дозволені файли, feedback, verify-результати та список touchedFiles; жодного прихованого глобального стану в поведінкових гарантіях не використовується.
+`buildVerifyFeedbackPrompt` і `buildFixPrompt` працюють як спільний шар керування поведінкою: перша підсилює наступну verify-ітерацію точним залишком порушень, друга задає початкові межі рунґа для правки. Обидві підтримують один і той самий semantic-collateral guard: зміни мають бути механічними та прив’язаними до дозволеного набору файлів, без підміни логіки правила.
+
+Результат `runAgentFix` повертається як стан спроби з переліком зачеплених файлів, телеметрією, помилкою або успіхом, а також rollback для fail-шляхів. За межі потоку можуть пройтися локальні fail-safe гілки; решта помилок не ховається й може підніматися назовні.
+
+Changelog: `npx @7n/rules lint changelog` — виконано успішно.
 
 ## Публічний API
 
@@ -37,6 +41,10 @@ addendum 2026-07-05): слабкі локальні моделі схильні
 verdict-veto consumer-а (re-check) відхиляє такі правки поза target-файлами.
 - runAgentFix — Проводить ОДНУ агентну fix-спробу (рунг) для правила.
 
+## Сценарії використання
+
+- `llm-lib/tests/agent-fix.test.mjs` (buildFixPrompt; error-шляхи (без git/pi)) — містить правило, порушення, інструкцію ast_facts/self_check; feedback додається лише за наявності; блок обмежень: лише механічні зміни, без хардкоду/симуляції (semantic-collateral guard); anchoredEdits: інструкція read_anchored/edit_anchored лише при увімкненому профілі; targetFiles: перелік додається лише за наявності; ще 24
+
 ## Гарантії поведінки
 
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.

package/lib/docs/agent-skill.md

@@ -3,31 +3,43 @@ type: JS Module
 title: agent-skill.mjs
 resource: llm-lib/lib/agent-skill.mjs
 docgen:
-  crc: 085ebccf
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: b7312bad
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:error
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Виконує один скіл `@nitra/cursor` як вбудованого pi-агента через публічну функцію `runAgentSkill`: подає готовий промпт у сесію, де агент сам **читає, редагує й створює файли та виконує shell-команди** (`bash`) у робочому каталозі. Це повний user-trust (паритет із ручним `claude -p`) — write-guard не накладається, бо скіл запускає користувач явно. Модель береться з однієї тири (`min`/`avg`/`max`, дефолт `max`). Будь-яка помилка перехоплюється (fail-safe) і повертається у результаті, а не кидається назовні.
+Організовує один запуск skill і керує його виконанням у межах поточного контексту, щоб агент отримував потрібний стан для роботи. Має локальні fail-safe гілки для контрольованих збоїв; інші помилки можуть поширюватися назовні.
 
 ## Поведінка
 
-1. Ініціалізація сесії агента: Визначає конфігурацію агента на основі вказаних параметрів, включаючи обраний рівень моделі, робочу директорію та рівень обчислення.
-2. Виконання скілу: Запускає агентну сесію з поданим промптом.
-3. Обробка відповідей: Під час виконання скілу, відповіді асистента виводяться у стандартний потік виводу.
-4. Моніторинг: Відстежується кількість ітерацій та викликів інструментів.
-5. Захист від нескінченності: Застосовується механізм обмеження кількості ітерацій (`TURN_CEILING`) та загального тайм-ауту для запобігання зависанню.
-6. Обробка збоїв: У разі виникнення помилки під час ініціалізації, конфігурації або виконання, вона фіксується, а функція повертає стан невдачі.
-7. Фіналізація: Після завершення виконання (успішно або через таймаут/переповнення ліміту) збирається телеметрія, яка включає статистику сесії, і результат повертається у вигляді об'єкта з інформацією про успішність.
+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.
 
 ## Публічний API
 
-runAgentSkill — Викликає певний агентський функціонал (скіл) через платформу pi з визначеними параметрами складності та обмеженнями виконання; опція `maxTokens` задає per-call стелю відповіді сесії (undefined → дефолт пакета, 0 → без стелі).
+- runAgentSkill — Виконує ОДИН скіл агентно через pi.
+
+## Сценарії використання
+
+- `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
 
 ## Гарантії поведінки
 
-- Повний user-trust: агент має read/edit/write/bash і мутує проєкт у робочому каталозі (без write-guard).
-- Runaway-backstop: перевищення стелі ітерацій (`N_CURSOR_SKILL_TURN_CEILING`) або таймауту (`N_CURSOR_SKILL_TIMEOUT_MS`) обриває сесію.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe); повертає `{ ok, telemetry, error }`.
-- Pi вантажиться lazy (тверда межа CI — модуль pi-free до першого виклику).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.

package/lib/docs/anchored-edit.md

@@ -3,32 +3,40 @@ type: JS Module
 title: anchored-edit.mjs
 resource: llm-lib/lib/anchored-edit.mjs
 docgen:
-  crc: 6ac40e43
+  crc: 7b38e0d2
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Строге hash-anchored редагування рядків (Фаза A2 run-harness): заміна built-in `read`/`edit` для fix-профілів. Кожен рядок файлу отримує 3-символьний base36-якір від sha256 вмісту; правка застосовується лише при точному збігу якоря з поточним станом рядка. Мета — прибрати collateral слабких моделей (переписаний файл, літеральний `\n\n`): жодного fuzzy-match, мовчазного переміщення чи автокорекції. Референс патерну — pi-hashline-edit-pro (вендориться ідея, не пакет).
+Файл описує роботу з текстом через рядки, привʼязані до номера та очікуваного вмісту. `lineAnchor` створює привʼязку для окремого рядка, `renderAnchored` подає файл у вигляді таких привʼязаних рядків, `applyAnchoredEdits` застосовує правки лише після звірки очікуваного стану, а `createAnchoredTools` надає цей сценарій як набір інструментів.
+
+Це потрібно, щоб правки вносилися в конкретні місця файлу й не застосовувалися, коли цільовий рядок більше не відповідає очікуваному вмісту.
 
 ## Поведінка
 
-Рендер (`renderAnchored`) віддає рядки у форматі `якір|номер|текст` (нумерація з 1, опційний діапазон включно). Застосування (`applyAnchoredEdits`) атомарне на файл: усі правки спершу валідуються (існування рядка, збіг якоря, відсутність дублю номера) — хоч одна розбіжність означає повну відмову з переліком `stale`-причин, файл не змінюється. Валідні правки застосовуються знизу вгору, тож номери рядків у пакеті правок не зсуваються; `newText` заміняє рядок (може бути багаторядковим), `null` — видаляє.
+`lineAnchor` задає правило привʼязки рядків до їхнього вмісту. `renderAnchored` використовує це правило, щоб перетворити поточний текст файла на рядки з якорем, номером і вмістом; такий результат призначений для подальшого формування точкових правок.
+
+`applyAnchoredEdits` приймає правки, підготовлені на основі anchored-подання, і перед зміною тексту повторно звіряє номери рядків та якорі з актуальним вмістом. Якщо хоча б одна правка більше не відповідає файлу або список правок неоднозначний, зміни не застосовуються взагалі. Це зберігає атомарність і дозволяє явно повідомити про stale-стан замість часткового редагування.
 
-Tool-фабрика (`createAnchoredTools`) створює пару pi-tools: `read_anchored` (файл або діапазон в anchored-форматі; неіснуючий файл — структурована помилка) і `edit_anchored` (правки `{anchor, line, newText}`; stale → JSON-відмова з інструкцією перечитати файл; для нових файлів чесно відсилає до `write`). `defineTool` передається caller-ом — модуль лишається pi-free; fs-операції інжектовані для тестів.
+`createAnchoredTools` з’єднує цей потік із pi-tools: читання файла повертає anchored-подання через `renderAnchored`, а редагування пропускає запропоновані зміни через `applyAnchoredEdits` і лише після успішної перевірки записує новий вміст. Результати повертаються як текстові відповіді tool-викликів, включно з причинами відмови для наступної спроби.
 
 ## Публічний API
 
-lineAnchor — 3-символьний base36-якір від sha256 вмісту рядка (детермінований, чутливий до будь-якої зміни тексту).
-renderAnchored — anchored-подання вмісту файлу для читання агентом.
-applyAnchoredEdits — атомарне застосування пакету правок або структурована відмова `{ok:false, stale:[…]}`.
-createAnchoredTools — фабрика tool-дефініцій `read_anchored`/`edit_anchored` для customTools pi-сесії.
+- lineAnchor — Якір рядка на основі вмісту рядка.
+- renderAnchored — Рендерить вміст файлу у anchored-форматі: `якір|номер|текст`, нумерація з 1.
+- applyAnchoredEdits — Атомарно застосовує anchored-правки до вмісту файлу.
+
+Валідація перед застосуванням: кожна правка перевіряється на існування рядка та збіг якоря з поточним вмістом. Якщо хоча б одна правка stale, нічого не застосовується. Заміна рядка може містити кілька рядків; видалення рядка також підтримується. Дублікати номера рядка у списку правок — теж відмова через двозначність.
+- createAnchoredTools — Фабрика пари pi-tools `read_anchored`/`edit_anchored`.
 
-## Де використовується
+`defineTool` передається caller-ом. Обидва tools повертають результат текстом, щоб відповідь містила причину відмови і підказку для наступного кроку.
 
-`agent-fix.mjs`: `opts.anchoredEdits` перемикає toolset сесії (built-in `read`/`edit` прибираються, `write` лишається для нових файлів). `edit_anchored` внесений у WRITE_TOOLS write-guard — той самий scope/denylist veto, pre-image snapshot і rollback, що й у built-in write-tools. Opt-in у cursor: env `N_LLM_FIX_ANCHORED` (default-worker).
+## Сценарії використання
 
 ## Гарантії поведінки
 
-- Атомарність на файл: часткове застосування пакету правок неможливе.
-- Якір прив'язаний лише до вмісту рядка; номер рядка звіряється окремо — розбіжність будь-якого з двох дає відмову.
-- Чисті функції не торкаються диска; запис робить лише `edit_anchored` (під write-guard).
+- (специфічних машинно-виведених гарантій немає)

package/lib/docs/batch.md

@@ -3,45 +3,31 @@ type: JS Module
 title: batch.mjs
 resource: llm-lib/lib/batch.mjs
 docgen:
-  crc: 5e13af10
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
-  score: 100
+  crc: 10b603cc
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 80
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Тип 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 завжди йде емуляцією).
+Тип 2b (OpenAI-сумісний API, batch) — **лише емуляція** у v1 (рішення Р,
+задача T6): чанкований конкурентний прогін через Тип 2a
+(`llm_lib::local_cloud`) під інтерфейсом `submit → progress → results` —
+той самий інтерфейс, яким говорив би й справжній OpenAI Batch API
+(`/v1/batches`, v2), якому локальний 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 повертає результати в тому ж порядку, що й вхідні items; для кожного item результат містить або `ok`, або `error`.
-
-Для кожного item `customId` має бути унікальним у межах одного виклику; конфлікт ідентифікаторів лишається на стороні викликача.
-
-За помилок виконання batch у відповіді зберігається один результат на кожен вхідний item, тож користувацький контракт не зводиться до часткової втрати елементів.
-
-`onProgress`, якщо заданий, отримує агрегований прогрес виконання для всього набору items.
+Тонкий JS-клієнт до Rust-крейта `llm_lib::batch` через napi FFI
+in-process (`llm-lib/crates/llm-lib-napi`) — жодного власного чанкінгу
+тут (анти-приклад, якого це узагальнює: `mlmail/use-summary.js` чанкує
+переклади проти omlx вручну, з вистражданими лімітами).
 
 ## Публічний 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`).
 
 ## Сценарії використання
 

package/lib/docs/body-capture.md

@@ -3,25 +3,43 @@ type: JS Module
 title: body-capture.mjs
 resource: llm-lib/lib/body-capture.mjs
 docgen:
-  crc: 3e3be25e
+  crc: f4c5b984
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:error
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Захоплення повних тіл LLM-викликів (prompt+response) — заміна колишнього requests.jsonl myllm-проксі, з перевагою: працює і для CLOUD-викликів (проксі бачив лише local), і не залежить від запущеного myllm. Увімкнено за замовчуванням — вимикається N_LLM_TRACE_BODIES=0. Не pi-coupled — публічний модуль пакета.
+Файл керує локальним захопленням тіл LLM-викликів, щоб трасування могло посилатися на окремий артефакт із повним вмістом взаємодії.
+
+`bodiesDir` визначає місце для таких артефактів, `bodyCaptureEnabled` вирішує, чи дозволене захоплення, а `captureBody` зберігає тіло виклику для подальшого аналізу.
+
+Окремі локальні fail-safe гілки повертають порожнє значення замість винятку, коли захоплення неможливе або недоречне. Інші помилки можуть поширюватися назовні.
 
 ## Поведінка
 
-captureBody — пише JSON-файл у ~/.n-cursor/llm-bodies/<chainId або caller>/<step>.json (ts, caller, chainId, chainStep, model, promptHash, prompt, output, usage, error); best-effort, ніколи не кидає; no-op (повертає null) коли body-capture вимкнено. При записі перевіряє сумарний розмір стору і видаляє найстаріші файли понад N_LLM_BODIES_MAX_MB (дефолт 500).
+`captureBody` є точкою запису: спершу звіряє дозвіл через `bodyCaptureEnabled`, потім визначає корінь сховища через `bodiesDir` або переданий override, групує запис за ланцюжком чи викликачем і зберігає повне тіло LLM-виклику у JSON-файл.
+
+Дані приходять із раннера LLM-виклику: фактичний prompt, відповідь або помилка, модель, usage та ідентифікатори трасування. Результат іде у файлове сховище, а назовні повертається шлях до створеного файлу або `null`, якщо захоплення вимкнене чи запис не вдався.
+
+Захоплення увімкнене за замовчуванням і вимикається лише явним значенням `N_LLM_TRACE_BODIES=0`. Корінь сховища береться із `N_LLM_BODIES_DIR`, а без нього — з користувацької директорії під `.n-cursor/llm-bodies`.
+
+Після успішного запису `captureBody` підтримує ліміт сховища: коли сумарний обсяг перевищує налаштований бюджет, найстаріші файли видаляються best-effort. Помилки запису, створення директорій або очищення не мають ламати LLM-виклик; у таких випадках модуль відмовляється від захоплення і повертає порожній результат.
 
 ## Публічний API
 
-bodiesDir() — корінь стору (env N_LLM_BODIES_DIR).
-bodyCaptureEnabled() — чи увімкнено (N_LLM_TRACE_BODIES!=='0').
-captureBody(record, opts?) — шлях збереженого файлу або null.
+- bodiesDir — Корінь стору (env-override `N_LLM_BODIES_DIR`).
+- bodyCaptureEnabled — Чи body-capture увімкнено (дефолт увімкнено — вимикають свідомо `N_LLM_TRACE_BODIES=0`).
+- captureBody — Захоплює одне тіло LLM-виклику (no-op, якщо `N_LLM_TRACE_BODIES` не `'1'`).
+
+## Сценарії використання
+
+- `llm-lib/tests/body-capture.test.mjs` (bodyCaptureEnabled/bodiesDir; captureBody) — увімкнено за замовчуванням; N_LLM_TRACE_BODIES=0 вимикає; bodiesDir — env-override; no-op (null) коли вимкнено; пише JSON-файл під chainId, повне поле prompt/output/usage/error; ще 5
 
 ## Гарантії поведінки
 
-- Best-effort: жодна файлова помилка не валить виклик LLM.
-- Ретеншн: сумарний розмір стору не росте необмежено (авто-очистка найстаріших файлів).
-- Компоненти шляху (chainId/caller/step) санітизуються — без directory traversal.
+- Містить локальні fail-safe гілки; інші помилки можуть поширюватися назовні.
+- Деякі локальні fail-safe гілки повертають порожнє значення (напр. `null`) замість винятку.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "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.11.0",
-    "@7n/llm-lib-linux-x64": "2.11.0"
+    "@7n/llm-lib-darwin-arm64": "2.9.7",
+    "@7n/llm-lib-linux-x64": "2.9.7"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "~0.80.10",