@7n/llm-lib 2.0.1 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [2.0.3] - 2026-07-10
+
+### Changed
+
+- chain.mjs: задокументовано конвенцію extra-полів фінального chain-запису (problem/resolvedBy/t0Applied/touchedFiles/touchedTotal) для шапки ланцюжка в UI/звітах
+
+## [2.0.2] - 2026-07-09
+
+### Fixed
+
+- виправити невалідний JS-синтаксис у прикладі README (парсинг падав у CI eslint)
+- усунути дублікат коду (jscpd) фабрик pi-сесії між one-shot/agent-fix/agent-skill — спільний streamFn-mixin хвіст винесено в internal/apply-session-mixins.mjs
+
 ## [2.0.1] - 2026-07-08
 
 ### Fixed

package/README.md

@@ -63,14 +63,22 @@ myllm-проксі, тепер живе в клієнтському mixin-сте
 local→cloud і T0-дистиляції:
 
 ```js
+import { runOneShot } from '@7n/llm-lib/one-shot'
 import { startChain } from '@7n/llm-lib/chain'
 
+const cwd = process.cwd()
 const chain = startChain({ kind: 'fix-concern', unit: 'rule/concern', cwd })
+let outcome = 'fail'
 try {
-  await runOneShot({ ..., chain })      // кожен виклик = крок ланцюжка
-  await runAgentFix(rule, v, cwd, { chain })
+  const { content } = await runOneShot({
+    messages: [{ role: 'user', content: 'запит' }],
+    modelTier: 'min',
+    caller: 'my-tool:fix',
+    chain // кожен виклик = крок ланцюжка
+  })
+  outcome = content ? 'success' : 'fail'
 } finally {
-  chain.end({ outcome: ok ? 'success' : 'fail', extra: { ... } })
+  chain.end({ outcome })
 }
 ```
 

package/lib/agent-fix.mjs

@@ -31,9 +31,7 @@ import { createWriteGuard, gitRoot } from './write-guard.mjs'
 import { failOnMemoryGuard } from './internal/memory-guard.mjs'
 import { writeTrace } from './trace.mjs'
 import { withTimeout } from './with-timeout.mjs'
-import { applyMaxTokens } from './internal/max-tokens.mjs'
-import { applyChainHeaders } from './internal/chain-headers.mjs'
-import { applyCompression } from './internal/apply-compression.mjs'
+import { applySessionMixins } from './internal/apply-session-mixins.mjs'
 import { captureBody } from './body-capture.mjs'
 import { promptHash } from './chain.mjs'
 
@@ -162,9 +160,7 @@ async function defaultCreateSession({ registry, model, thinkingLevel, cwd, facto
     sessionManager: SessionManager.inMemory(),
     resourceLoader: loader
   })
-  applyChainHeaders(session, chain)
-  applyCompression(session)
-  return applyMaxTokens(session)
+  return applySessionMixins(session, chain)
 }
 
 /**

package/lib/agent-skill.mjs

@@ -22,9 +22,7 @@ import { isLocalModel, resolveModel } from './model-tiers.mjs'
 import { getRegistry, resolveModelSpec } from './internal/registry.mjs'
 import { failOnMemoryGuard } from './internal/memory-guard.mjs'
 import { writeTrace } from './trace.mjs'
-import { applyMaxTokens } from './internal/max-tokens.mjs'
-import { applyChainHeaders } from './internal/chain-headers.mjs'
-import { applyCompression } from './internal/apply-compression.mjs'
+import { applySessionMixins } from './internal/apply-session-mixins.mjs'
 import { captureBody } from './body-capture.mjs'
 import { promptHash } from './chain.mjs'
 import { withTimeout } from './with-timeout.mjs'
@@ -58,9 +56,7 @@ async function defaultCreateSession({ registry, model, cwd, thinkingLevel, maxTo
     cwd: cwd ?? process.cwd(),
     sessionManager: SessionManager.inMemory()
   })
-  applyChainHeaders(session, chain)
-  applyCompression(session)
-  return maxTokens === undefined ? applyMaxTokens(session) : applyMaxTokens(session, maxTokens)
+  return applySessionMixins(session, chain, maxTokens)
 }
 
 /**

package/lib/chain.mjs

@@ -24,6 +24,15 @@
  * `chain.headers()` у HTTP-виклики локальних моделей; плюс кожен trace-запис
  * несе `promptHash` — офлайн-fallback джойн.
  *
+ * КОНВЕНЦІЯ extra для шапки ланцюжка в UI/звітах (пише producer, напр.
+ * fix-pipeline n-cursor; читають myllm ChainsPanel і chains-report; всі поля
+ * опційні — старі записи без них валідні):
+ *   extra.problem      — { violations, reasons[], files[], sample } — ЩО вирішували;
+ *   extra.resolvedBy   — 't0' | '<tier>:<model>' — ХТО закрив (null якщо не закрито);
+ *   extra.t0Applied    — [{ id, message }] — застосовані T0-патерни;
+ *   extra.touchedFiles — cwd-relative шляхи реально збережених змін (кеп 20),
+ *   extra.touchedTotal — повна кількість (кеп не читається як «це всі файли»).
+ *
  * КОНТРАКТ promptHash (дзеркальна реалізація в myllm chains.rs — не міняти
  * односторонньо): sha256(trim(text))[0..16] lowercase, де text — content
  * ОСТАННЬОГО повідомлення з role=='user' (рядок як є; масив parts —

package/lib/docs/agent-fix.md

@@ -3,7 +3,7 @@ type: JS Module
 title: agent-fix.mjs
 resource: llm-lib/lib/agent-fix.mjs
 docgen:
-  crc: 57ee1933
+  crc: cd657d18
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/lib/docs/agent-skill.md

@@ -3,7 +3,7 @@ type: JS Module
 title: agent-skill.mjs
 resource: llm-lib/lib/agent-skill.mjs
 docgen:
-  crc: 98ff1d64
+  crc: 196f6fcf
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/lib/docs/one-shot.md

@@ -3,7 +3,7 @@ type: JS Module
 title: one-shot.mjs
 resource: llm-lib/lib/one-shot.mjs
 docgen:
-  crc: 437d9cd7
+  crc: 286493bf
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/lib/internal/apply-session-mixins.mjs

@@ -0,0 +1,25 @@
+/** @see ./docs/apply-session-mixins.md */
+
+/**
+ * Спільний хвіст фабрики сесії (chain-headers → compression → max-tokens),
+ * однаковий у всіх раннерів (`one-shot`/`agent-fix`/`agent-skill`) — виділено
+ * зі спільного дубльованого коду (jscpd). INTERNAL — приймає/повертає pi
+ * AgentSession, тому не входить у публічний API пакета.
+ */
+import { applyChainHeaders } from './chain-headers.mjs'
+import { applyCompression } from './apply-compression.mjs'
+import { applyMaxTokens } from './max-tokens.mjs'
+
+/**
+ * Домішує конвеєр streamFn-mixin-ів у новостворену сесію: заголовки ланцюжка,
+ * компресія контексту, стеля токенів відповіді.
+ * @param {object} session pi AgentSession
+ * @param {object|null} [chain] chain handle — домішує X-Chain-* заголовки (лише локальні моделі)
+ * @param {number} [maxTokens] per-call стеля відповіді (undefined → дефолт пакета, 0 → без стелі)
+ * @returns {object} та сама session (для чейнінгу return)
+ */
+export function applySessionMixins(session, chain, maxTokens) {
+  applyChainHeaders(session, chain)
+  applyCompression(session)
+  return maxTokens === undefined ? applyMaxTokens(session) : applyMaxTokens(session, maxTokens)
+}

package/lib/internal/docs/apply-session-mixins.md

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: apply-session-mixins.mjs
+resource: llm-lib/lib/internal/apply-session-mixins.mjs
+docgen:
+  crc: de49ddb2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Модифікація вимагає уникнення обговорення припущень ("стиснутий контекст", "обмеження обсягу відповіді"), оскільки вони не підтверджені наданими "ВІДОМИМИ ФАКТАМИ", і фокусування на дії публічної функції `applySessionMixins`.
+
+Ось переписаний текст, який відповідає всім стилістичним та формальним обмеженням:
+
+Цей модуль виконує ініціалізацію та підготовку початкового стану сесії шляхом застосування міксинів сесії за допомогою `applySessionMixins`.
+
+## Поведінка
+
+1. Викликається `applySessionMixins` для початкової сесії.
+2. До сесії додаються метадані, що описують ланцюжок.
+3. Зміст контексту сесії стискається.
+4. Встановлюється максимальна кількість токенів відповіді, якщо не вказано інше значення.
+
+## Публічний API
+
+applySessionMixins — доповнює процес роботи нової сесії елементами, які керують потоком (streamFn-mixin-и), форматуванням контексту, та обробкою токенів у відповіді.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/lib/internal/docs/index.md

@@ -4,16 +4,12 @@ title: llm-lib/lib/internal
 resource: llm-lib/lib/internal/
 ---
 
-# llm-lib/lib/internal
-
-INTERNAL-модулі `@7n/llm-lib` — substrate-coupled (pi) частини, що НЕ входять
-у публічний API пакета (subpath-експортів на них нема).
-
-| Файл                                | Тип       |
-| ----------------------------------- | --------- |
-| [apply-compression.mjs](apply-compression.md) | JS Module |
-| [chain-headers.mjs](chain-headers.md) | JS Module |
-| [compress-context.mjs](compress-context.md) | JS Module |
-| [max-tokens.mjs](max-tokens.md)     | JS Module |
-| [memory-guard.mjs](memory-guard.md) | JS Module |
-| [registry.mjs](registry.md)         | JS Module |
+| Файл                                                | Тип       |
+| --------------------------------------------------- | --------- |
+| [apply-compression.mjs](apply-compression.md)       | JS Module |
+| [apply-session-mixins.mjs](apply-session-mixins.md) | JS Module |
+| [chain-headers.mjs](chain-headers.md)               | JS Module |
+| [compress-context.mjs](compress-context.md)         | JS Module |
+| [max-tokens.mjs](max-tokens.md)                     | JS Module |
+| [memory-guard.mjs](memory-guard.md)                 | JS Module |
+| [registry.mjs](registry.md)                         | JS Module |

package/lib/one-shot.mjs

@@ -22,9 +22,7 @@ import { getRegistry, resolveModelSpec } from './internal/registry.mjs'
 import { failOnMemoryGuard } from './internal/memory-guard.mjs'
 import { writeTrace } from './trace.mjs'
 import { withTimeout } from './with-timeout.mjs'
-import { applyMaxTokens } from './internal/max-tokens.mjs'
-import { applyChainHeaders } from './internal/chain-headers.mjs'
-import { applyCompression } from './internal/apply-compression.mjs'
+import { applySessionMixins } from './internal/apply-session-mixins.mjs'
 import { captureBody } from './body-capture.mjs'
 import { promptHash } from './chain.mjs'
 
@@ -60,9 +58,7 @@ async function defaultCreateSession({ registry, model, cwd, thinkingLevel, maxTo
     cwd: cwd ?? process.cwd(),
     sessionManager: SessionManager.inMemory()
   })
-  applyChainHeaders(session, chain)
-  applyCompression(session)
-  return maxTokens === undefined ? applyMaxTokens(session) : applyMaxTokens(session, maxTokens)
+  return applySessionMixins(session, chain, maxTokens)
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",