@7n/rules 1.43.1 → 1.44.0

package/rules/test/coverage/lib/classify/docs/prompt.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: prompt.mjs
+resource: npm/src/coverage-classify/prompt.mjs
+docgen:
+  crc: b4dd4c52
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Промпт-builder для `coverage-classify` генерує контекстні інструкції. Він визначає статичну роль класифікатора (`SYSTEM_PROMPT`), яка кешується через `cache_control: ephemeral` при виклику API. Динамічно він збирає деталі кожного мутанта (location, source $\pm$10, tests, git) у промпт, що здійснюється функцією `buildUserPrompt`. Процес працює з механізмом fail-safe, запобігаючи виникненню винятків, а кешування відбувається в межах одного прогону. `SYSTEM_PROMPT` явно вимагає строго валідний JSON без markdown-fence і prose навколо нього, з інструкцією екранувати лапки/backslash усередині `reason`/`suggestedTest` і триматись у межах довжини — це знижує частку відповідей, які не парсяться як JSON.
+
+## Поведінка
+
+SYSTEM_PROMPT визначає роль класифікатора мутацій і встановлює чіткий JSON-схему для відповіді, де мутації класифікуються як 'worth-testing', 'equivalent', 'defensive', 'glue' або 'wrapper'.
+buildUserPrompt збирає повний контекст для класифікації конкретного мутанта, включаючи фрагмент вихідного коду навколо місця мутації, вміст супутніх тестів та останні зміни у Git для створення деталізованого промпта.
+
+## Публічний API
+
+SYSTEM_PROMPT — Визначає основні інструкції та обмеження для AI-агента.
+buildUserPrompt — Формує запит від користувача для розпізнавання конкретного мутагенту.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.

package/rules/test/coverage/lib/classify/docs/verdict-schema.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: verdict-schema.mjs
+resource: npm/src/coverage-classify/verdict-schema.mjs
+docgen:
+  crc: 51190b81
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл визначає `VerdictSchema` для структурованого відображення результатів класифікації, які генерує LLM-класифікатор (coverage-classify). Функція `parseVerdict` відповідає за вилучення та валідацію JSON-структури з необробленого тексту відповіді LLM, що дозволяє класифікувати вихід у категорії: `worth-testing`, `equivalent`, `defensive`, `glue` або `wrapper`. Витяг JSON толерантний до типових LLM-огріхів (markdown fences, prose навколо JSON, неекрановані лапки/backslash/control-символи всередині string-значень), які на практиці регулярно ламали наївний `JSON.parse`.
+
+## Поведінка
+
+VerdictSchema: Визначає структуру даних для результатів класифікації, отриманих від LLM.
+parseVerdict: Знаходить перший JSON-об'єкт у сирому тексті відповіді (розрізаючи markdown-fence, якщо він є), ремонтує типові огріхи всередині string-значень (неекрановані лапки, невалідні backslash-escape як `\d`, буквальні control-символи, trailing comma), обрізає candidate по balanced-brace межі першого `{…}` (ігноруючи prose після нього), а надто довгі `reason`/`suggestedTest` — обрізає до ліміту схеми замість falling через `too_big`-помилку валідації. Лише після цього валідує через `VerdictSchema`.
+
+## Публічний API
+
+VerdictSchema — схема, що описує очікувану структуру відповіді від LLM.
+parseVerdict — видобуває та перевіряє відповідь від LLM щодо відповідності схемі VerdictSchema; кидає помилку, якщо JSON не знайдено, JSON не парситься навіть після repair, або результат не проходить схему.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Repair-крок ніколи не звертається до мережі чи файлової системи — чиста трансформація рядка.

package/rules/test/coverage/lib/classify/index.mjs

@@ -0,0 +1,140 @@
+/**
+ * Public API класифікатора: classify(survived, cwd, opts) → verdicts[]
+ *
+ * Routing через pi SDK (callText):
+ *   1. Cache lookup → hit → використати збережений verdict.
+ *   2. Cache miss → Tier 1 (N_LOCAL_MIN_MODEL через pi) → parseVerdict.
+ *   3. Tier 1 fail → Tier 2 (N_CLOUD_MIN_MODEL через pi) → parseVerdict.
+ *   4. Tier 2 fail → conservative fallback worth-testing/confidence=0.
+ */
+import { join } from 'node:path'
+
+import { callText } from '../llm.mjs'
+import { CLOUD_MIN, LOCAL_MIN } from '@7n/llm-lib/model-tiers'
+import { startChain } from '@7n/llm-lib/chain'
+import { deriveCacheKey, readCache, writeCache } from './cache.mjs'
+import { buildUserPrompt, SYSTEM_PROMPT } from './prompt.mjs'
+import { parseVerdict } from './verdict-schema.mjs'
+
+const FALLBACK_VERDICT = {
+  verdict: 'worth-testing',
+  confidence: 0,
+  reason: 'LLM-classification unavailable, conservative fallback (treat as worth-testing)'
+}
+
+/**
+ * Викликає pi через callText з опційним model-id.
+ * @param {string} prompt готовий промпт класифікації
+ * @param {string} model provider/model-id або '' для pi-дефолту
+ * @param {string} cwd корінь проєкту
+ * @param {{chain?: object}} [callOpts] chain handle поточного мутанта
+ * @returns {Promise<string>} сирий текст відповіді моделі
+ */
+function callModel(prompt, model, cwd, { chain } = {}) {
+  return callText(prompt, { cwd, chain, ...(model && { model }) })
+}
+
+/**
+ * Два тири: tier1 (local-min) → tier2 (cloud-min) → FALLBACK_VERDICT.
+ * Кожен мутант — окремий ланцюжок (kind: mutant-classify): tier1 = крок 1,
+ * tier2 = крок 2; fallback-вердикт = outcome:'fail' (LLM не впорався).
+ * @param {{file: string, mutants: object[]}} group група survived-мутантів одного файлу
+ * @param {object} mutant один survived-мутант групи
+ * @param {string} cwd корінь проєкту
+ * @param {(prompt: string, model: string, cwd: string, callOpts?: {chain?: object}) => Promise<string>} callModelFn виклик моделі (інжект у тестах)
+ * @param {string} tier1 model-spec першого тиру ('' = pi-дефолт)
+ * @param {string} tier2 model-spec другого тиру ('' = pi-дефолт)
+ * @param {typeof startChain} makeChain фабрика ланцюжка
+ * @returns {Promise<object>} verdict
+ */
+async function classifyOne(group, mutant, cwd, callModelFn, tier1, tier2, makeChain) {
+  const prompt = `${SYSTEM_PROMPT}\n\n${buildUserPrompt({ ...mutant, file: group.file }, cwd)}`
+  const loc = `${group.file}:${mutant.line}:${mutant.col}`
+  const chain = makeChain({ kind: 'mutant-classify', unit: loc, cwd })
+
+  try {
+    const text = await callModelFn(prompt, tier1, cwd, { chain })
+    const verdict = parseVerdict(text)
+    chain.end({ outcome: 'success', extra: verdictExtra(verdict, mutant) })
+    return verdict
+  } catch {
+    try {
+      const text = await callModelFn(prompt, tier2, cwd, { chain })
+      const verdict = parseVerdict(text)
+      chain.end({ outcome: 'success', extra: verdictExtra(verdict, mutant) })
+      return verdict
+    } catch (error) {
+      console.warn(`⚠ coverage classify: ${loc} both tiers failed: ${error.message}`)
+      chain.end({ outcome: 'fail', extra: { error: String(error.message ?? error).slice(0, 200) } })
+      return { ...FALLBACK_VERDICT }
+    }
+  }
+}
+
+/**
+ * Extra-поля фінального chain-запису мутанта.
+ * @param {{verdict: string, confidence: number}} verdict розпарсений вердикт
+ * @param {{replacement?: string}} mutant мутант
+ * @returns {object} extra
+ */
+function verdictExtra(verdict, mutant) {
+  return {
+    verdict: verdict.verdict,
+    confidence: verdict.confidence,
+    replacement: String(mutant.replacement ?? '').slice(0, 120)
+  }
+}
+
+/**
+ * Класифікує survived мутантів через pi (N_LOCAL_MIN_MODEL → N_CLOUD_MIN_MODEL → fallback).
+ * @param {Array<{file: string, mutants: object[], exampleTest?: object|null, recommendationText?: string|null}>} survived survived-мутанти з виміру, згруповані по файлах
+ * @param {string} cwd корінь проєкту
+ * @param {{cachePath?: string, callModel?: (prompt: string, model: string, cwd: string, callOpts?: {chain?: object}) => Promise<string>,
+ *   tier1?: string, tier2?: string, startChain?: typeof startChain}} [opts] `tier1`/`tier2` — явні model-specs (дефолт: LOCAL_MIN/CLOUD_MIN пакета;
+ *   інжектовні, бо тир-константи фіксуються при імпорті й у тестах не стабляться через env); `startChain` — фабрика ланцюжка (інжект для тестів)
+ * @returns {Promise<Array<{key: string, verdict: object}>>} вердикти по кожному мутанту
+ */
+export async function classify(survived, cwd, opts = {}) {
+  const cachePath = opts.cachePath ?? join(cwd, 'reports', 'coverage-classify.cache.json')
+  const callModelFn = opts.callModel ?? callModel
+  const makeChain = opts.startChain ?? startChain
+  const tier1 = opts.tier1 ?? LOCAL_MIN
+  const tier2 = opts.tier2 ?? CLOUD_MIN
+  const cacheModel = `${tier1 || 'default'}+${tier2 || 'cloud'}`
+
+  const cache = readCache(cachePath)
+  if (cache.model !== cacheModel) {
+    cache.entries = {}
+    cache.model = cacheModel
+  }
+
+  const verdicts = []
+  for (const group of survived) {
+    for (const mutant of group.mutants) {
+      const lookupKey = `${group.file}:${mutant.line}:${mutant.col}:${mutant.replacement}`
+      const cacheKey = deriveCacheKey(join(cwd, group.file), mutant)
+
+      let verdict = null
+      if (cacheKey && cache.entries[cacheKey]) {
+        const cached = cache.entries[cacheKey]
+        verdict = {
+          verdict: cached.verdict,
+          confidence: cached.confidence,
+          reason: cached.reason,
+          ...(cached.suggestedTest && { suggestedTest: cached.suggestedTest })
+        }
+      }
+      if (!verdict) {
+        verdict = await classifyOne(group, mutant, cwd, callModelFn, tier1, tier2, makeChain)
+        if (cacheKey) {
+          cache.entries[cacheKey] = { ...verdict, classifiedAt: new Date().toISOString() }
+        }
+      }
+
+      verdicts.push({ key: lookupKey, verdict })
+    }
+  }
+
+  writeCache(cachePath, cache)
+  return verdicts
+}

package/rules/test/coverage/lib/classify/prompt.mjs

@@ -0,0 +1,136 @@
+/**
+ * Промпт-builder для coverage-classify.
+ * SYSTEM_PROMPT — статичний, кешується через cache_control: ephemeral у API call.
+ * buildUserPrompt — асемблює per-mutant контекст (location, source ±10, tests, git).
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+const CONTEXT_LINES = 10
+const TEST_FILE_MAX_LINES = 2000
+
+export const SYSTEM_PROMPT = `You are a mutation testing classifier.
+
+For each survived Stryker mutant, classify it into exactly one verdict:
+
+- **worth-testing**: pure logic with real branches that should be tested. The mutant
+  exposes a missing assertion in a unit test. Recommend a test approach.
+- **equivalent**: the mutated code is behaviorally indistinguishable from the original
+  (e.g., both branches produce the same observable output, or the mutant lies on dead
+  code). You MUST cite a concrete reason referencing input flow or output equivalence.
+- **defensive**: the branch guards against an impossible state given input contracts
+  or type system. You MUST identify the invariant that makes the state unreachable.
+- **glue**: thin CLI entrypoint, factory, or boilerplate (e.g., runStandardRule
+  wrapper, fix.mjs stubs). Integration tests via subprocess cover the behavior.
+  Name the integration test or pattern.
+- **wrapper**: thin shell around an external tool (spawnSync, fetch, dynamic import).
+  The wrapper has no logic worth unit-testing in isolation; behavior comes from the
+  wrapped tool. Name the integration test or pattern.
+
+Output ONLY a single JSON object matching this schema — no markdown code fences, no
+prose before or after, nothing but the JSON object itself:
+
+\`\`\`
+{
+  "verdict": "worth-testing" | "equivalent" | "defensive" | "glue" | "wrapper",
+  "confidence": number 0-1,
+  "reason": string (20-500 chars; concrete code-level reference, not "seems like"),
+  "suggestedTest": string (max 300 chars; required only when verdict is worth-testing)
+}
+\`\`\`
+
+The response must be valid JSON, parseable by a strict JSON.parse. In particular:
+- "reason" and "suggestedTest" are single-line strings: no literal newlines — if you
+  need to separate points, use "; " instead of a line break.
+- Escape every double quote and backslash that occurs inside a string value (e.g. a
+  quoted identifier like \`user.role\`, or a regex like /\\d+/, must become
+  \\"user.role\\" and /\\\\d+/ inside the JSON string).
+- Stay within the 500/300 char limits above — summarize instead of running long;
+  a response that gets cut off for length is worse than a terse one.
+
+Confidence guidance:
+- 0.9+: cite specific code fragment, identifier, or input contract proving the verdict.
+- 0.7-0.9: strong inference from visible code structure.
+- <0.7: ambiguity, lacking context, or unfamiliar pattern. Be honest.
+
+Never invent integration test names. If you cannot identify a covering test, use
+worth-testing with low confidence instead of glue/wrapper.
+`
+
+/**
+ * Витягує describe/test/it title з рядка тексту.
+ * @param {string} content повний текст test-файла
+ * @returns {string} список "describe: <title>" / "test: <title>" або порожній
+ */
+function extractTestTitles(content) {
+  const titles = []
+  for (const match of content.matchAll(/^[ \t]{0,16}(describe|test|it)\(['"`](.{1,300}?)['"`]/gmu)) {
+    titles.push(`${match[1]}: ${match[2]}`)
+  }
+  return titles.join('\n') || '(no describe/test blocks found)'
+}
+
+/**
+ * Будує користувацький промпт для класифікації одного мутанта.
+ * @param {{file: string, line: number, col: number, mutantType: string, original: string, replacement: string}} mutant параметри мутанта (file — відносний до cwd)
+ * @param {string} cwd корінь проєкту
+ * @returns {string} user prompt
+ */
+export function buildUserPrompt(mutant, cwd) {
+  const absPath = join(cwd, mutant.file)
+
+  // Source context
+  let srcContext = '(source file unavailable)'
+  if (existsSync(absPath)) {
+    const lines = readFileSync(absPath, 'utf8').split('\n')
+    const start = Math.max(0, mutant.line - 1 - CONTEXT_LINES)
+    const end = Math.min(lines.length, mutant.line + CONTEXT_LINES)
+    srcContext = lines
+      .slice(start, end)
+      .map((l, i) => `${start + i + 1}: ${l}`)
+      .join('\n')
+  }
+
+  // Existing tests
+  const testPath = join(dirname(absPath), 'tests', `${basename(absPath, '.mjs')}.test.mjs`)
+  let existingTests = '(no test file)'
+  if (existsSync(testPath)) {
+    const content = readFileSync(testPath, 'utf8')
+    if (content.split('\n').length > TEST_FILE_MAX_LINES) {
+      existingTests = extractTestTitles(content)
+    } else {
+      existingTests = content
+    }
+  }
+
+  // Recent git activity (graceful если нет git або untracked)
+  let recentActivity = '(no git history)'
+  try {
+    const out = execFileSync('git', ['log', '-1', '--format=%ar', '--', absPath], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim()
+    if (out) recentActivity = out
+  } catch {
+    // git unavailable or file untracked — keep placeholder
+  }
+
+  return `# Mutant
+File: ${mutant.file}
+Line: ${mutant.line}:${mutant.col}
+Type: ${mutant.mutantType}
+Original code: \`${mutant.original}\`
+Mutated to: \`${mutant.replacement}\`
+
+# Source context (±${CONTEXT_LINES} lines)
+${srcContext}
+
+# Existing tests
+${existingTests}
+
+# Recent activity
+File last modified: ${recentActivity}
+`
+}

package/rules/test/coverage/lib/classify/verdict-schema.mjs

@@ -0,0 +1,163 @@
+/**
+ * Zod-схема для verdict-відповіді LLM-класифікатора (coverage-classify).
+ * parseVerdict — витяг JSON з raw-text LLM-відповіді + validate.
+ *
+ * Категорії:
+ *   - worth-testing: pure logic, real branches — пиши тест
+ *   - equivalent:    мутант поведінково еквівалентний (не killable)
+ *   - defensive:     гілка для impossible state (не killable)
+ *   - glue:          CLI entry / runStandardRule wrapper (integration covers)
+ *   - wrapper:       тонкий spawn/fetch wrapper (integration covers)
+ */
+import { z } from 'zod'
+
+// Трохи ширше за prompt-ліміт (500) — запас на моделі, які трохи перевищують
+// інструкцію; понад це вже truncate-имо самі перед валідацією (REASON_SOFT_MAX нижче).
+const REASON_SOFT_MAX = 500
+const SUGGESTED_TEST_SOFT_MAX = 300
+
+export const VerdictSchema = z.object({
+  verdict: z.enum(['worth-testing', 'equivalent', 'defensive', 'glue', 'wrapper']),
+  confidence: z.number().min(0).max(1),
+  reason: z.string().min(20).max(REASON_SOFT_MAX),
+  suggestedTest: z.string().max(SUGGESTED_TEST_SOFT_MAX).optional()
+})
+
+const VALID_JSON_ESCAPES = new Set(['"', '\\', '/', 'b', 'f', 'n', 'r', 't', 'u'])
+
+/** Пробільний символ (для peekNextStructural). */
+const WHITESPACE_RE = /\s/u
+/** Fenced json-блок (потрійні бектіки) у raw-відповіді LLM. */
+const FENCED_JSON_RE = /```(?:json)?\s*([\s\S]*?)```/iu
+
+/**
+ * Перший non-whitespace символ від `from` — рішення, чи подвійна лапка
+ * закриває рядок, чи це буквальна лапка всередині значення.
+ * @param {string} text текст
+ * @param {number} from індекс, з якого шукати
+ * @returns {string | undefined} символ або undefined якщо кінець тексту
+ */
+function peekNextStructural(text, from) {
+  let i = from
+  while (i < text.length && WHITESPACE_RE.test(text[i])) i++
+  return text[i]
+}
+
+/**
+ * Одночасно (1) ремонтує типові LLM-огріхи всередині JSON string-літералів
+ * (неекрановані `"`/backslash/control-символи — джерело "Bad escaped character"
+ * і "Expected ',' or '}'" помилок JSON.parse) і (2) обрізає candidate на
+ * balanced-brace межі першого `{…}`, ігноруючи prose після нього.
+ * @param {string} text candidate-текст, що починається з `{`
+ * @returns {string} repaired JSON-текст (balanced або best-effort до кінця тексту)
+ */
+function repairAndBalance(text) {
+  let out = ''
+  let inString = false
+  let depth = 0
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+
+    if (inString) {
+      if (ch === '\\') {
+        const next = text[i + 1]
+        if (next !== undefined && VALID_JSON_ESCAPES.has(next)) {
+          out += ch + next
+          i++
+        } else {
+          out += String.raw`\\` // невалідний escape (напр. \d, \s) → буквальний backslash
+        }
+        continue
+      }
+      if (ch === '"') {
+        const nextStructural = peekNextStructural(text, i + 1)
+        const closesString = nextStructural === undefined || ',}]:'.includes(nextStructural)
+        if (closesString) {
+          inString = false
+          out += ch
+        } else {
+          out += String.raw`\"` // буквальна лапка всередині значення (напр. цитата коду)
+        }
+        continue
+      }
+      if (ch === '\n') {
+        out += String.raw`\n`
+        continue
+      }
+      if (ch === '\r') {
+        out += String.raw`\r`
+        continue
+      }
+      if (ch === '\t') {
+        out += String.raw`\t`
+        continue
+      }
+      out += ch
+      continue
+    }
+
+    if (ch === '"') {
+      inString = true
+      out += ch
+      continue
+    }
+    if (ch === '{') {
+      depth++
+      out += ch
+      continue
+    }
+    if (ch === '}') {
+      depth--
+      out += ch
+      if (depth === 0) return out
+      continue
+    }
+    if (ch === ',' && '}]'.includes(peekNextStructural(text, i + 1) ?? '')) {
+      continue // trailing comma перед закриттям — прибираємо
+    }
+    out += ch
+  }
+  return out
+}
+
+/**
+ * Витягує JSON-об'єкт з raw-text LLM-відповіді. Толерантний до markdown
+ * code fences і prose до/після JSON-блоку.
+ * @param {string} rawText raw-text відповідь LLM
+ * @returns {string | null} candidate-текст, що починається з першого `{`, або null
+ */
+function extractJsonCandidate(rawText) {
+  const fenced = rawText.match(FENCED_JSON_RE)
+  const text = fenced ? fenced[1] : rawText
+  const start = text.indexOf('{')
+  return start === -1 ? null : text.slice(start)
+}
+
+/**
+ * Витягує JSON-об'єкт з raw-text LLM-відповіді і валідує через VerdictSchema.
+ * Толерантний до markdown fences, prose навколо JSON, неекранованих лапок/
+ * backslash/control-символів усередині string-значень (типові LLM-огріхи, що
+ * ламають наївний `JSON.parse`).
+ * @param {string} rawText raw-text відповідь LLM
+ * @returns {{verdict: string, confidence: number, reason: string, suggestedTest?: string}} verdict
+ * @throws {Error} якщо JSON не знайдено, не парситься навіть після repair, або не відповідає схемі
+ */
+export function parseVerdict(rawText) {
+  const candidate = extractJsonCandidate(rawText)
+  if (!candidate) {
+    throw new Error('No JSON object found in LLM response')
+  }
+  const repaired = repairAndBalance(candidate)
+  const json = JSON.parse(repaired)
+
+  if (json && typeof json === 'object') {
+    if (typeof json.reason === 'string' && json.reason.length > REASON_SOFT_MAX) {
+      json.reason = json.reason.slice(0, REASON_SOFT_MAX)
+    }
+    if (typeof json.suggestedTest === 'string' && json.suggestedTest.length > SUGGESTED_TEST_SOFT_MAX) {
+      json.suggestedTest = json.suggestedTest.slice(0, SUGGESTED_TEST_SOFT_MAX)
+    }
+  }
+
+  return VerdictSchema.parse(json)
+}

package/rules/test/coverage/lib/llm.mjs

@@ -0,0 +1,100 @@
+/**
+ * Тонкий адаптер `@7n/test` над `@7n/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 { env } from 'node:process'
+import { runOneShot } from '@7n/llm-lib/one-shot'
+import { runAgentSkill } from '@7n/llm-lib/agent-skill'
+
+/**
+ * Стеля відповіді моделі для подвоєння на `stopReason: 'length'` — межа
+ * `maxTokens` реєстру для локальної моделі (див. `~/.pi/agent/models.json`).
+ */
+const MAX_TOKENS_CEILING = 32_768
+
+/**
+ * Таймаут агентного виклику (паритет зі старим spawnSync pi CLI). Override:
+ * `N_CURSOR_AGENT_TIMEOUT_MS` — для великих проєктів, де навіть один batch
+ * (див. `coverage-fix.mjs#fixSurvivedMutants`) потребує більше часу.
+ */
+const AGENT_TIMEOUT_MS = Number(env.N_CURSOR_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.chain] chain handle (`@7n/llm-lib/chain`) — виклик стає кроком ланцюжка
+ * @param {object} [opts.deps] інжекти для тестів (прокидаються у runOneShot)
+ * @returns {Promise<string>} текстова відповідь моделі
+ */
+export async function callText(prompt, opts = {}) {
+  let maxTokens = opts.maxTokens
+  let lengthRetried = Boolean(opts._lengthRetried)
+
+  while (true) {
+    const r = await runOneShot({
+      messages: [{ role: 'user', content: prompt }],
+      modelSpec: opts.model ?? '',
+      maxTokens,
+      timeoutMs: 0,
+      cwd: opts.cwd,
+      caller: '7n-test:text',
+      chain: opts.chain ?? null,
+      deps: opts.deps
+    })
+    if (r.error) throw new Error(r.error)
+
+    // Обрізана генерація зі зниженою стелею — не палимо retry-цикли колера
+    // на «invalid block», а один раз повторюємо з подвоєною стелею.
+    if (r.stopReason === 'length' && maxTokens && maxTokens < MAX_TOKENS_CEILING && !lengthRetried) {
+      const doubled = Math.min(maxTokens * 2, MAX_TOKENS_CEILING)
+      console.log(`  ⚠ відповідь обрізана (stopReason: length) — повтор із maxTokens ${maxTokens} → ${doubled}`)
+      maxTokens = doubled
+      lengthRetried = true
+      continue
+    }
+
+    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.chain] chain handle (`@7n/llm-lib/chain`) — виклик стає кроком ланцюжка
+ * @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',
+    chain: opts.chain ?? null,
+    deps: opts.deps
+  })
+  if (r.error) throw new Error(r.error)
+}
+
+export { MEMORY_ERROR_RE } from '@7n/llm-lib/one-shot'