@7n/llm-lib 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [2.4.0] - 2026-07-11
+
+### Added
+
+- harness (Фаза A4): createHarness — декларативний фасад над runOneShot/runAgentFix/runAgentSkill (профіль-обʼєкт {schema_version, kind, ...} → делегація в раннер, per-виклик поля перекривають); + subpath-експорти anchored-edit, web-tools
+
 ## [2.3.0] - 2026-07-11
 
 ### Added

package/README.md

@@ -23,6 +23,7 @@ pi свідомо лишає на caller-а: model tiers, fail-fast політи
 
 | Імпорт | Що дає |
 | --- | --- |
+| `@7n/llm-lib/harness` | `createHarness({profiles})` → `{run(spec), profileNames()}` — декларативний фасад над раннерами (профіль-обʼєкт `{schema_version, kind, ...}` → делегація); `validateProfile(p)`, `HARNESS_SCHEMA_VERSION` |
 | `@7n/llm-lib/one-shot` | `runOneShot({messages, modelTier?, modelSpec?, ...})` → `{content, usage, error, model, caller}` |
 | `@7n/llm-lib/agent-fix` | `runAgentFix(ruleId, violation, cwd, opts)` → `{applied, touchedFiles, telemetry, error, rollback}`; `buildFixPrompt(...)` |
 | `@7n/llm-lib/agent-skill` | `runAgentSkill(prompt, opts)` → `{ok, telemetry, error}` |
@@ -35,6 +36,8 @@ pi свідомо лишає на caller-а: model tiers, fail-fast політи
 | `@7n/llm-lib/with-timeout` | `withTimeout(promise, ms, {onTimeout?, label?})` |
 | `@7n/llm-lib/prompt-budget` | `budgetFor(kind)`, `fitToBudget(chunks, maxChars)`, `packBatch(items, maxChars)`, `capText(text, maxChars)` |
 | `@7n/llm-lib/body-capture` | `captureBody(record, opts?)` (opt-in, `N_LLM_TRACE_BODIES=1`), `bodiesDir()`, `bodyCaptureEnabled()` |
+| `@7n/llm-lib/anchored-edit` | `createAnchoredTools({cwd, defineTool})`, `applyAnchoredEdits(content, edits)`, `lineAnchor(text)`, `renderAnchored(content, range?)` — hash-anchored строгі edit-tools (профіль `anchoredEdits`) |
+| `@7n/llm-lib/web-tools` | `createWebTools({defineTool})`, `fetchPage(url, opts?)`, `assertPublicHttpUrl(url)`, `resolveSearchProvider(env)` — web_search/web_fetch із SSRF-guard (профіль `webTools`) |
 
 `lib/internal/` (registry, memory-guard, max-tokens, chain-headers, compress-context,
 apply-compression) — НЕ публічний API: не імпортувати зовні пакета, subpath-експортів

package/lib/docs/harness.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: harness.mjs
+resource: llm-lib/lib/harness.mjs
+docgen:
+  crc: 3ff88af8
+---
+
+## Огляд
+
+Run-harness фасад (Фаза A4): єдиний декларативний вхід над трьома раннерами пакета (`runOneShot` / `runAgentFix` / `runAgentSkill`). Consumer описує ЩО запустити профілем-обʼєктом, а не набором позиційних opts; той самий профіль серіалізується у JSON — це те, що дозволяє майбутньому MT-адаптеру мапити вузол графа на конфігурацію без коду. Фасад тонкий: резолвить профіль у opts і делегує в наявний раннер, не дублюючи їхньої логіки (write-guard, verify-loop, toolset-и лишаються в раннерах).
+
+## Поведінка
+
+Профіль — обʼєкт `{ schema_version, kind, …налаштування }`, де `kind` (`fix`/`skill`/`one-shot`) привʼязує його до раннера, а решта полів (tier, model, timeoutMs, maxTokens, thinkingLevel, verifyMax, anchoredEdits, webTools) стають дефолтами opts. `schema_version` присутній з першої версії й перевіряється на сумісність — несумісний або невідомий `kind` дає структуровану помилку валідації ще до раннера.
+
+`createHarness({ profiles })` повертає обʼєкт із `run(spec)` і `profileNames()`. У `run` профіль задається іменем (з мапи) або інлайн-обʼєктом, а per-виклик поля (динаміка: cwd, violation, verify, messages, prompt тощо) зливаються поверх дефолтів профілю й перекривають збіжні. Далі harness делегує з правильними позиційними аргументами кожного раннера: `fix` → `(ruleId, violation, cwd, opts)`, `skill` → `(prompt, opts)`, `one-shot` → `(opts)`. Поля `kind`/`schema_version` у opts раннера не потрапляють.
+
+Раннери тягнуться lazy (динамічний import у гілці потрібного `kind`) — top-level модуль лишається вільним від pi; у тестах раннери інжектуються через `deps`.
+
+## Публічний API
+
+HARNESS_SCHEMA_VERSION — поточна версія схеми профілю.
+validateProfile — перевіряє `kind` і `schema_version`, повертає `{ok}` або `{ok:false, error}`.
+createHarness — будує harness із іменованих профілів; `run(spec)` запускає задачу, `profileNames()` перелічує профілі.
+
+## Гарантії поведінки
+
+- Контракт раннерів не змінюється: harness лише перекладає профіль+виклик у їхні аргументи й повертає їхній результат як є.
+- Невалідний/невідомий профіль зупиняється до виклику раннера (жодного часткового ефекту).
+- Top-level pi-free: жодного pi-import, поки не викликано `run` відповідного kind.

package/lib/harness.mjs

@@ -0,0 +1,119 @@
+/** @see ./docs/harness.md */
+
+/**
+ * Run-harness фасад (Фаза A4, дизайн 2026-07-11): єдиний декларативний вхід над
+ * трьома раннерами (`runOneShot` / `runAgentFix` / `runAgentSkill`).
+ *
+ * Мета — щоб consumer (inline-драбина n-cursor, майбутній MT-runner Фази B, 7n-test)
+ * описував ЩО запустити **профілем-обʼєктом**, а не набором позиційних opts, і щоб
+ * той самий профіль серіалізувався у JSON (Фаза B мапить `a.md`-вузол MT → профіль
+ * без коду). Фасад тонкий: він резолвить профіль у opts і делегує в наявний раннер,
+ * НЕ дублюючи їхню логіку (write-guard, verify-loop, toolset-и лишаються в раннерах).
+ *
+ * Профіль (усі поля опційні, крім прив'язки до раннера через `kind`):
+ *   { schema_version: 1, kind: 'fix'|'skill'|'one-shot',
+ *     tier, model, timeoutMs, maxTokens, thinkingLevel,
+ *     verifyMax, anchoredEdits, webTools }
+ * `schema_version` присутній з дня 1 — Фаза B хоче стабільності контракту.
+ *
+ * Модуль pi-free на рівні top-level: раннери самі роблять lazy pi-import у fix/skill
+ * гілці; `createHarness` лише готує замикання.
+ */
+
+/** Поточна версія схеми профілю. Несумісна зміна → bump + міграція consumer-ів. */
+export const HARNESS_SCHEMA_VERSION = 1
+
+/** Підтримувані види задач (прив'язка профілю до раннера). */
+const KINDS = new Set(['fix', 'skill', 'one-shot'])
+
+/**
+ * Валідує профіль: відомий `kind`, сумісний `schema_version`.
+ * @param {object} profile профіль-обʼєкт
+ * @returns {{ ok: true } | { ok: false, error: string }} результат валідації
+ */
+export function validateProfile(profile) {
+  if (!profile || typeof profile !== 'object') return { ok: false, error: 'профіль має бути обʼєктом' }
+  const v = profile.schema_version ?? HARNESS_SCHEMA_VERSION
+  if (v !== HARNESS_SCHEMA_VERSION) {
+    return { ok: false, error: `несумісний schema_version ${v} (очікується ${HARNESS_SCHEMA_VERSION})` }
+  }
+  if (!KINDS.has(profile.kind)) {
+    return { ok: false, error: `невідомий kind "${profile.kind}" (допустимі: ${[...KINDS].join(', ')})` }
+  }
+  return { ok: true }
+}
+
+/**
+ * Резолвить профіль + per-виклик поля у opts конкретного раннера.
+ * Профіль задає дефолти конфігурації, `call` — динаміку виклику (cwd, violation,
+ * verify, chain тощо); `call` перекриває збіжні поля профілю.
+ * @param {object} profile профіль-обʼєкт (валідований)
+ * @param {object} call per-виклик поля
+ * @returns {object} opts для раннера
+ */
+function resolveOpts(profile, call) {
+  const { schema_version: _sv, kind: _kind, ...profileOpts } = profile
+  return { ...profileOpts, ...call }
+}
+
+/**
+ * Створює harness із набором іменованих профілів.
+ * @param {{ profiles?: Record<string, object>,
+ *   deps?: { runOneShot?: (opts: object) => Promise<object>, runAgentFix?: (...args: unknown[]) => Promise<object>, runAgentSkill?: (prompt: string, opts: object) => Promise<object> } }} [args]
+ *   `profiles` — мапа імʼя→профіль; `deps` — інжекція раннерів (тести / кастомний wiring).
+ * @returns {{ run: (spec: object) => Promise<object>, profileNames: () => string[] }} harness
+ */
+export function createHarness({ profiles = {}, deps = {} } = {}) {
+  /**
+   * Лениво тягне раннер (pi-free top-level: імпорт лише при першому виклику потрібного kind).
+   * @param {string} kind вид задачі
+   * @returns {Promise<(...args: unknown[]) => Promise<object>>} функція-раннер
+   */
+  async function runnerFor(kind) {
+    if (kind === 'fix') {
+      if (deps.runAgentFix) return deps.runAgentFix
+      const mod = await import('./agent-fix.mjs')
+      return mod.runAgentFix
+    }
+    if (kind === 'skill') {
+      if (deps.runAgentSkill) return deps.runAgentSkill
+      const mod = await import('./agent-skill.mjs')
+      return mod.runAgentSkill
+    }
+    if (deps.runOneShot) return deps.runOneShot
+    const mod = await import('./one-shot.mjs')
+    return mod.runOneShot
+  }
+
+  /**
+   * Запускає задачу за профілем.
+   * @param {object} spec `{ profile: string|object, ...call }` — профіль за іменем або
+   *   інлайн-обʼєктом + per-виклик поля (`fix`: ruleId, violation, cwd, verify, targetFiles…;
+   *   `skill`: prompt, cwd…; `one-shot`: messages…).
+   * @returns {Promise<object>} результат відповідного раннера (контракт не змінюється)
+   */
+  async function run(spec = {}) {
+    const { profile: profileRef, ...call } = spec
+    const profile = typeof profileRef === 'string' ? profiles[profileRef] : profileRef
+    if (!profile) throw new Error(`профіль не знайдено: ${JSON.stringify(profileRef)}`)
+    const valid = validateProfile(profile)
+    if (!valid.ok) throw new Error(`невалідний профіль: ${valid.error}`)
+
+    const run = await runnerFor(profile.kind)
+    const opts = resolveOpts(profile, call)
+    if (profile.kind === 'fix') {
+      // runAgentFix(ruleId, violation, cwd, opts) — позиційні + opts.
+      const { ruleId, violation, cwd, ...rest } = opts
+      return run(ruleId, violation, cwd, rest)
+    }
+    if (profile.kind === 'skill') {
+      // runAgentSkill(prompt, opts) — prompt позиційний.
+      const { prompt, ...rest } = opts
+      return run(prompt, rest)
+    }
+    // one-shot: усе в одному obj-arg.
+    return run(opts)
+  }
+
+  return { run, profileNames: () => Object.keys(profiles) }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",
@@ -32,6 +32,9 @@
     "!**/*.test.mjs"
   ],
   "exports": {
+    "./harness": "./lib/harness.mjs",
+    "./anchored-edit": "./lib/anchored-edit.mjs",
+    "./web-tools": "./lib/web-tools.mjs",
     "./model-tiers": "./lib/model-tiers.mjs",
     "./chain": "./lib/chain.mjs",
     "./chains-report": "./lib/chains-report.mjs",