@7n/llm-lib 2.0.4 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.1.0] - 2026-07-11
+
+### Added
+
+- agent-fix: evidence-гейт verify-loop (Фаза A1) — opts.verify/verifyMax, фідбек провалу у ту саму сесію, телеметрія verifyAttempts
+
 ## [2.0.4] - 2026-07-10
 
 ### Changed

package/lib/agent-fix.mjs

@@ -15,6 +15,13 @@
  * error, rollback }` — застосуванням володіє worker, orchestrator робить лише зовнішній
  * verdict-recheck і за провалу кличе `rollback()` (clean-slate per rung).
  *
+ * Evidence-гейт (дизайн 2026-07-11, Фаза A1): опційний `opts.verify` — canonical
+ * перевірка від consumer-а. Після prompt-у harness сам жене verify; провал →
+ * вивід перевірки інʼєктиться фідбеком у ТУ САМУ сесію (до `verifyMax` додаткових
+ * ітерацій, у межах загального `timeoutMs` рунга). Гейт структурний, а не
+ * model-контракт: заяви агента про успіх не важать — джерело правди лишається
+ * зовнішнім. Без `verify` поведінка попередня (один прохід).
+ *
  * Pi вантажиться lazy (top-level import модуля pi-free). Логіка інжектована через
  * `deps` для unit-тестів; `deps.astContext` — споживацький AST-екстрактор (напр.
  * oxc-based у `@nitra/cursor`), без нього tool чесно відповідає «недоступний».
@@ -46,6 +53,18 @@ const TURN_CEILING = Number(env.N_LLM_FIX_TURN_CEILING ?? env.N_CURSOR_FIX_TURN_
  */
 const DEFAULT_TIMEOUT_MS = 300_000
 
+/**
+ * Дефолт додаткових verify-ітерацій (фідбек у ту саму сесію) при заданому `opts.verify`.
+ * Consumer-и тюнять per tier (local — менше, cloud — більше).
+ */
+const VERIFY_MAX_DEFAULT = 2
+
+/**
+ * Мінімальний залишок бюджету часу рунга, з яким ще є сенс запускати verify-ітерацію
+ * (менше — фідбек-prompt майже гарантовано не встигне, чесніше зупинитись одразу).
+ */
+const VERIFY_MIN_BUDGET_MS = 5000
+
 /**
  * Порожній rollback для fail-шляхів.
  * @returns {void}
@@ -54,6 +73,21 @@ function noop() {
   /* навмисно порожньо: нема чого відкочувати */
 }
 
+/**
+ * Будує фідбек-prompt verify-ітерації: точний вивід canonical-перевірки + нагадування
+ * обмежень (той самий semantic-collateral guard, що й у buildFixPrompt).
+ * @param {string} output вивід перевірки (порушення, що лишились)
+ * @returns {string} prompt для тієї самої сесії
+ */
+export function buildVerifyFeedbackPrompt(output) {
+  return (
+    'Перевірка правила показує, що порушення ДОСІ активне після твоїх правок:\n\n' +
+    `${output}\n\n` +
+    'Виправ залишок. Обмеження ті самі: лише механічні зміни, лише target-файли, ' +
+    'без хардкоду значень і симуляції поведінки.'
+  )
+}
+
 /**
  * Маркер недоступності `astContext`.
  * @returns {{ error: string }} повідомлення про недоступність AST facts
@@ -62,6 +96,48 @@ function astUnavailable() {
   return { error: 'ast_facts недоступний: consumer не надав astContext' }
 }
 
+/**
+ * Evidence-петля: canonical verify → (не ok) → фідбек у ТУ САМУ сесію, поки не ok /
+ * вичерпано `verifyMax` / вичерпано бюджет часу рунга (`timeoutMs` спільний з першим
+ * prompt-ом — нових таймерів не вводимо). Помилка самої перевірки — інфраструктурна:
+ * ітерації не палимо, чесний error. Зовнішній canonical re-detect consumer-а лишається
+ * джерелом правди — тут лише рання й точніша петля всередині рунга.
+ * @param {{ session: object, verify: (args: { touchedFiles: string[] }) => Promise<{ ok: boolean, output?: string }> | { ok: boolean, output?: string },
+ *   verifyMax: number, timeoutMs: number, startedAt: number, clock: () => number,
+ *   guard: { touchedFiles: () => string[] }, fixPrompt: string }} args контекст петлі.
+ * @returns {Promise<{ verifyAttempts: Array<{ ok: boolean, infra?: boolean }>, error: string|null }>} результат петлі.
+ */
+async function runVerifyLoop({ session, verify, verifyMax, timeoutMs, startedAt, clock, guard, fixPrompt }) {
+  const verifyAttempts = []
+  for (let attempt = 0; ; attempt++) {
+    let evidence
+    try {
+      evidence = await verify({ touchedFiles: guard.touchedFiles() })
+    } catch (verifyError) {
+      verifyAttempts.push({ ok: false, infra: true })
+      return { verifyAttempts, error: `verify: ${verifyError.message}` }
+    }
+    verifyAttempts.push({ ok: evidence?.ok === true })
+    if (evidence?.ok === true) return { verifyAttempts, error: null }
+    if (attempt >= verifyMax) {
+      return { verifyAttempts, error: `verify: порушення лишилось після ${attempt + 1} перевірок` }
+    }
+    const remainingMs = timeoutMs - (clock() - startedAt)
+    if (remainingMs < VERIFY_MIN_BUDGET_MS) {
+      return { verifyAttempts, error: 'verify: бюджет часу рунга вичерпано' }
+    }
+    try {
+      await withTimeout(session.prompt(buildVerifyFeedbackPrompt(evidence?.output ?? '')), remainingMs, {
+        onTimeout: () => session.abort?.(),
+        label: 'fix-verify'
+      })
+    } catch (promptError) {
+      failOnMemoryGuard(promptError.message, fixPrompt)
+      return { verifyAttempts, error: promptError.message }
+    }
+  }
+}
+
 /**
  * Будує fix-промпт для рунга: правило + порушення + (опц.) target-файли + (опц.) feedback
  * попереднього провалу + жорсткий блок обмежень (лише механічні зміни) + інструкція
@@ -172,6 +248,8 @@ async function defaultCreateSession({ registry, model, thinkingLevel, cwd, facto
  *   model: string, tier?: string, feedback?: object, caller?: string, timeoutMs?: number, ruleText?: string,
  *   chain?: object,
  *   targetFiles?: string[],
+ *   verify?: (args: { touchedFiles: string[] }) => Promise<{ ok: boolean, output?: string }> | { ok: boolean, output?: string },
+ *   verifyMax?: number,
  *   deps?: { createSession?: (args: object) => Promise<object>, getRegistry?: () => Promise<object>,
  *            registry?: object, root?: string|null,
  *            astContext?: (path: string) => object,
@@ -190,6 +268,8 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     ruleText,
     chain = null,
     targetFiles,
+    verify = null,
+    verifyMax = VERIFY_MAX_DEFAULT,
     deps = {}
   } = opts
   const createSession = deps.createSession ?? defaultCreateSession
@@ -307,6 +387,14 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     failOnMemoryGuard(error, fixPrompt)
   }
 
+  // Evidence-гейт: verify → (не ok) → фідбек у ТУ САМУ сесію (див. runVerifyLoop).
+  let verifyAttempts = []
+  if (verify && !error) {
+    const loop = await runVerifyLoop({ session, verify, verifyMax, timeoutMs, startedAt, clock, guard, fixPrompt })
+    verifyAttempts = loop.verifyAttempts
+    error = loop.error
+  }
+
   const touchedFiles = guard.touchedFiles()
   const telemetry = {
     rule: ruleId,
@@ -318,6 +406,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     edits: guard.state.editLog,
     blocks: guard.state.blocks,
     backstopHit,
+    verifyAttempts,
     wallMs: clock() - startedAt
   }
   // Usage кроку для chain-агрегатів: сума по turns агентної сесії.
@@ -348,6 +437,8 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     toolCallCount,
     touchedFiles,
     backstopHit,
+    verifyAttempts: verifyAttempts.length,
+    verifyOk: verifyAttempts.length > 0 ? verifyAttempts.at(-1).ok : null,
     wallMs: clock() - startedAt,
     error,
     ...chain?.traceFields()

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: cd657d18
+  crc: 0f2be7f8
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
@@ -18,10 +18,13 @@ buildFixPrompt готує текстовий промпт, що містить
 runAgentFix виконує повний агентний цикл для спроби виправлення порушення правила, включаючи взаємодію з інструментами, застосування патча та фіксацію телеметрії.
 Виклик сесії огорнутий timeout-гонкою: `opts.timeoutMs` (дефолт 300s, коли consumer не передав значення) на спрацюванні abort-ить сесію і повертає помилку `fix timeout …` — зависла LLM-сесія (напр. мертва SSE) не блокує виклик назавжди.
 
+Evidence-гейт (опційний `opts.verify`, Фаза A1 run-harness): після prompt-у модуль сам запускає canonical-перевірку consumer-а; провал інʼєктиться фідбеком у ту саму сесію — до `opts.verifyMax` додаткових ітерацій (дефолт 2), у межах того самого `timeoutMs` (залишок бюджету < 5s — чесна зупинка без ітерації). Гейт структурний: заяви агента про успіх не важать, джерелом правди лишається зовнішня перевірка. Помилка самої перевірки — інфраструктурна: ітерації не витрачаються, повертається `error` з префіксом `verify:`. Без `verify` — поведінка попередня (один прохід). Спроби фіксуються у `telemetry.verifyAttempts` і у trace (`verifyAttempts`, `verifyOk`).
+
 ## Публічний API
 
 buildFixPrompt — формує інструкцію для виправлення проблеми, включаючи відповідне правило, описане порушення, опційний перелік target-файлів (єдині наявні файли, які дозволено редагувати) та можливий відгук з попередньої невдалої спроби; містить обовʼязковий блок обмежень semantic-collateral guard (лише механічні зміни: без зміни бізнес-логіки, без хардкоду значень, без симуляції поведінки — spec pi-migration §12, addendum 2026-07-05) і директиву щодо кроків перед редагуванням та самоперевірки.
-runAgentFix — виконує єдину спробу виправлення коду з боку агента для заданого правила, використовуючи вказані параметри (модель, рівень, зворотний зв'язок, тощо) та ін'єкції для тестування.
+buildVerifyFeedbackPrompt — формує фідбек-повідомлення verify-ітерації: точний вивід canonical-перевірки + нагадування обмежень semantic-collateral guard.
+runAgentFix — виконує єдину спробу виправлення коду з боку агента для заданого правила, використовуючи вказані параметри (модель, рівень, зворотний зв'язок, verify-гейт, тощо) та ін'єкції для тестування.
 
 ## Гарантії поведінки
 

package/package.json

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