@7n/llm-lib 2.2.1 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- web-tools (Фаза A3): web_search/web_fetch для cloud-профілів — SSRF-guard (кожен redirect-hop), мінімальна html→text екстракція без нових залежностей, один search-провайдер за ключем (Brave/Tavily/Exa, N_LLM_SEARCH_PROVIDER); opts.webTools у runAgentFix (дефолт off)
+
 ## [2.2.1] - 2026-07-11
 
 ### Changed

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/agent-fix.mjs

@@ -33,6 +33,7 @@
 import { env } from 'node:process'
 import { homedir } from 'node:os'
 import { createAnchoredTools } from './anchored-edit.mjs'
+import { createWebTools } from './web-tools.mjs'
 import { getRegistry, resolveModelSpec } from './internal/registry.mjs'
 import { isLocalModel, thinkingLevelForTier } from './model-tiers.mjs'
 import { createWriteGuard, gitRoot } from './write-guard.mjs'
@@ -204,7 +205,8 @@ async function defaultCreateSession({
   astContext,
   selfCheck,
   chain,
-  anchoredEdits = false
+  anchoredEdits = false,
+  webTools = false
 }) {
   const { createAgentSession, SessionManager, DefaultResourceLoader, SettingsManager, defineTool } =
     await import('@earendil-works/pi-coding-agent')
@@ -253,6 +255,12 @@ async function defaultCreateSession({
     tools = ['grep', 'find', 'write', 'ls', 'ast_facts', 'self_check', 'read_anchored', 'edit_anchored']
     customTools.push(readTool, editTool)
   }
+  // A3: web-доступ — лише за явним профілем (cloud-тири за дизайном); read-only tools.
+  if (webTools) {
+    const { searchTool, fetchTool } = createWebTools({ defineTool })
+    tools = [...tools, 'web_search', 'web_fetch']
+    customTools.push(searchTool, fetchTool)
+  }
 
   const { session } = await createAgentSession({
     modelRegistry: registry,
@@ -279,6 +287,7 @@ async function defaultCreateSession({
  *   verify?: (args: { touchedFiles: string[] }) => Promise<{ ok: boolean, output?: string }> | { ok: boolean, output?: string },
  *   verifyMax?: number,
  *   anchoredEdits?: boolean,
+ *   webTools?: boolean,
  *   deps?: { createSession?: (args: object) => Promise<object>, getRegistry?: () => Promise<object>,
  *            registry?: object, root?: string|null,
  *            astContext?: (path: string) => object,
@@ -300,6 +309,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     verify = null,
     verifyMax = VERIFY_MAX_DEFAULT,
     anchoredEdits = false,
+    webTools = false,
     deps = {}
   } = opts
   const createSession = deps.createSession ?? defaultCreateSession
@@ -359,6 +369,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
       astContext,
       selfCheck,
       anchoredEdits,
+      webTools,
       // Заголовки кореляції — лише локальним моделям (myllm стоїть тільки перед ними).
       chain: modelSpec && isLocalModel(modelSpec) ? chain : null
     })
@@ -471,6 +482,7 @@ export async function runAgentFix(ruleId, violation, cwd, opts = {}) {
     verifyAttempts: verifyAttempts.length,
     verifyOk: verifyAttempts.length > 0 ? verifyAttempts.at(-1).ok : null,
     anchoredEdits,
+    webTools,
     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: 730809af
+  crc: 83a189d4
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
@@ -18,6 +18,8 @@ buildFixPrompt готує текстовий промпт, що містить
 runAgentFix виконує повний агентний цикл для спроби виправлення порушення правила, включаючи взаємодію з інструментами, застосування патча та фіксацію телеметрії.
 Виклик сесії огорнутий timeout-гонкою: `opts.timeoutMs` (дефолт 300s, коли consumer не передав значення) на спрацюванні abort-ить сесію і повертає помилку `fix timeout …` — зависла LLM-сесія (напр. мертва SSE) не блокує виклик назавжди.
 
+Web-профіль (опційний `opts.webTools`, Фаза A3): додає read-only tools `web_search`/`web_fetch` (див. web-tools.md; SSRF-guard, ліміти розміру) — для правил із зовнішнім знанням на cloud-тирах; прапорець у трейсі, дефолт вимкнено.
+
 Anchored-профіль (опційний `opts.anchoredEdits`, Фаза A2): toolset сесії заміняє built-in `read`/`edit` на строгі `read_anchored`/`edit_anchored` (див. anchored-edit.md; `write` лишається для нових файлів, під тим самим write-guard), а промпт отримує інструкцію anchored-циклу. Прапорець фіксується у трейсі (`anchoredEdits`) для A/B-аналізу; дефолт вимкнено.
 
 Evidence-гейт (опційний `opts.verify`, Фаза A1 run-harness): після prompt-у модуль сам запускає canonical-перевірку consumer-а; провал інʼєктиться фідбеком у ту саму сесію — до `opts.verifyMax` додаткових ітерацій (дефолт 2), у межах того самого `timeoutMs` (залишок бюджету < 5s — чесна зупинка без ітерації). Гейт структурний: заяви агента про успіх не важать, джерелом правди лишається зовнішня перевірка. Помилка самої перевірки — інфраструктурна: ітерації не витрачаються, повертається `error` з префіксом `verify:`. Без `verify` — поведінка попередня (один прохід). Спроби фіксуються у `telemetry.verifyAttempts` і у trace (`verifyAttempts`, `verifyOk`).

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/docs/web-tools.md

@@ -0,0 +1,37 @@
+---
+type: JS Module
+title: web-tools.mjs
+resource: llm-lib/lib/web-tools.mjs
+docgen:
+  crc: 4242c966
+---
+
+## Огляд
+
+Web-доступ для cloud-профілів run-harness (Фаза A3): пара pi-tools `web_search`/`web_fetch` — мінімальне ядро без нових залежностей (референс — pi-web-access, без його fallback-ланцюгів провайдерів і browser-режимів). Вмикається лише явним профілем consumer-а (agent-fix `opts.webTools`, за дизайном — cloud-тири); дефолт вимкнено.
+
+## Поведінка
+
+`web_fetch` ходить лише на публічні http(s)-адреси: SSRF-guard блокує інші схеми, `localhost`/`*.local`/`*.internal` і літеральні приватні IP (v4-діапазони, v6 loopback/link-local/ULA); redirect-и проходяться вручну (до 3 hop-ів) з guard-перевіркою кожного hop-а. HTML зводиться до тексту власним мінімальним стрипером (script/style/noscript вирізаються ітеративно без regex-backtracking, блокові теги → переноси, entity декодуються); json/plain віддаються як є. Відповідь обрізається лімітом (`maxChars`, дефолт 20k символів) з чесним прапорцем `truncated`; таймаут запиту 20s.
+
+`web_search` працює через ОДНОГО провайдера: явний `N_LLM_SEARCH_PROVIDER` або перший наявний ключ (`BRAVE_API_KEY` → `TAVILY_API_KEY` → `EXA_API_KEY`); результати нормалізуються до `{title, url, snippet}`. Без жодного ключа tool чесно повертає структуровану відмову з інструкцією конфігурації — не виняток.
+
+Вміст сторінок повертається tool-result-ом (дані, не інструкції) — prompt-injection зі сторінок не отримує системного рівня; помилки обох tools — структурований JSON-текст із причиною.
+
+## Публічний API
+
+assertPublicHttpUrl — SSRF-guard: розбирає URL або кидає Error з причиною відмови.
+htmlToText — мінімальна html→text екстракція (без DOM-залежностей).
+fetchPage — fetch з guard-ом на кожному redirect-hop-і, таймаутом і лімітом розміру.
+resolveSearchProvider — вибір search-провайдера за env.
+createWebTools — фабрика tool-дефініцій `web_search`/`web_fetch` (defineTool і fetch інжектяться — модуль pi-free).
+
+## Де використовується
+
+`agent-fix.mjs`: `opts.webTools: true` додає обидва tools у сесію (перші споживачі — правила з зовнішнім знанням: pin-перевірки ga, taze-подібні). Прапорець фіксується у trace для аналізу.
+
+## Гарантії поведінки
+
+- Жодного мережевого виклику без явного tool-виклику агента; лише http/https на публічні адреси.
+- Відповіді обмежені за розміром; guard-відмови детерміновані й пояснені.
+- Модуль pi-free; усі зовнішні ефекти (fetch, env) інжектовані — тести без мережі.

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/lib/web-tools.mjs

@@ -0,0 +1,321 @@
+/** @see ./docs/web-tools.md */
+
+/**
+ * Web-доступ для cloud-профілів run-harness (Фаза A3, дизайн 2026-07-11).
+ *
+ * Мінімальне ядро без нових залежностей (референс — pi-web-access, без його
+ * fallback-ланцюгів провайдерів, browser-cookie режимів і video-екстракції):
+ *   - `web_fetch` — global fetch → текстова екстракція (html→text власним
+ *     мінімальним стрипером, json/plain — як є) з лімітом розміру.
+ *   - `web_search` — ОДИН провайдер за конфігом: `N_LLM_SEARCH_PROVIDER` або
+ *     перший наявний ключ (`BRAVE_API_KEY` → `TAVILY_API_KEY` → `EXA_API_KEY`).
+ *
+ * Безпека (нова поверхня довіри — URL формує модель):
+ *   - SSRF-guard: лише http/https; блок localhost/*.local та літеральних IP
+ *     приватних діапазонів; redirect-и проходяться вручну (до 3 hop-ів) із
+ *     guard-перевіркою КОЖНОГО hop-а.
+ *   - Вміст сторінок повертається як tool-result (дані, не інструкції) —
+ *     prompt-injection зі сторінок не отримує системного рівня.
+ *   - Ліміт відповіді (`maxChars`) — проти роздування контексту.
+ *
+ * Модуль pi-free: `defineTool` і fetch інжектяться; ввімкнення — профілем
+ * consumer-а (agent-fix `opts.webTools`, лише cloud-тири за дизайном).
+ */
+
+import { env as processEnv } from 'node:process'
+
+/** Дефолтний таймаут одного web-запиту. */
+const FETCH_TIMEOUT_MS = 20_000
+/** Дефолтний ліміт символів відповіді tool-а (проти роздування контексту). */
+const DEFAULT_MAX_CHARS = 20_000
+/** Максимум redirect-hop-ів при ручному проході. */
+const MAX_REDIRECTS = 3
+/** Кількість результатів пошуку за замовчуванням. */
+const DEFAULT_SEARCH_COUNT = 5
+
+const PRIVATE_V4 = /^(?:0\.|10\.|127\.|169\.254\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.)/
+const PRIVATE_V6 = /^(?:::1|::|fe80:|f[cd][0-9a-f]{2}:)/i
+const HTML_CONTENT_TYPE = /text\/html|application\/xhtml/i
+const BLOCK_CLOSE_TAGS = /<\/(?:p|div|li|h[1-6]|tr|section|article|blockquote|pre)>/gi
+const BR_HR_TAGS = /<(?:br|hr)\s*\/?>/gi
+const SPACES = /[ \t]+/g
+const BLANK_LINES = /\n{3,}/g
+
+/**
+ * SSRF-guard: чи можна ходити на URL. Кидає Error з причиною при відмові.
+ * Блокує не-http(s), localhost/*.local/*.internal і літеральні приватні IP
+ * (v4-діапазони, v6 loopback/link-local/ULA). DNS-резолюція не робиться —
+ * захист від літералів; довірений периметр consumer-а лишається його політикою.
+ * @param {string} rawUrl URL з tool-input
+ * @returns {URL} розібраний URL (для подальшого fetch)
+ */
+export function assertPublicHttpUrl(rawUrl) {
+  let url
+  try {
+    url = new URL(rawUrl)
+  } catch {
+    throw new Error(`невалідний URL: ${rawUrl}`)
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`заборонена схема ${url.protocol} (лише http/https)`)
+  }
+  const host = url.hostname.toLowerCase()
+  if (host === 'localhost' || host.endsWith('.local') || host.endsWith('.internal')) {
+    throw new Error(`заборонений хост: ${host}`)
+  }
+  const bare = host.replaceAll(/^\[|\]$/g, '')
+  if (PRIVATE_V4.test(bare)) throw new Error(`приватна IPv4-адреса заборонена: ${host}`)
+  if (PRIVATE_V6.test(bare)) throw new Error(`приватна IPv6-адреса заборонена: ${host}`)
+  return url
+}
+
+/**
+ * Ітеративно (без regex-backtracking) вирізає блоки `<tag …>…</tag>`.
+ * @param {string} html вихідний html
+ * @param {string} tag імʼя тега (lowercase)
+ * @returns {string} html без блоків тега
+ */
+function stripTagBlocks(html, tag) {
+  const open = `<${tag}`
+  const close = `</${tag}>`
+  const lower = () => html.toLowerCase()
+  for (;;) {
+    const start = lower().indexOf(open)
+    if (start === -1) return html
+    const end = lower().indexOf(close, start)
+    if (end === -1) return html.slice(0, start)
+    html = `${html.slice(0, start)} ${html.slice(end + close.length)}`
+  }
+}
+
+/**
+ * Char-scan стрип решти тегів (`<…>` → пробіл) без regex.
+ * @param {string} text html після блокових замін
+ * @returns {string} текст без тегів
+ */
+function stripTags(text) {
+  let out = ''
+  let i = 0
+  while (i < text.length) {
+    const lt = text.indexOf('<', i)
+    if (lt === -1) {
+      out += text.slice(i)
+      break
+    }
+    out += text.slice(i, lt)
+    const gt = text.indexOf('>', lt + 1)
+    if (gt === -1) break
+    out += ' '
+    i = gt + 1
+  }
+  return out
+}
+
+/**
+ * Мінімальна html→text екстракція: викидає script/style/noscript, блокові теги
+ * зводить до переносів, решту тегів стрипає, декодує базові entity, стискає
+ * порожні рядки. Це свідомо НЕ readability (без DOM-залежностей) — достатньо,
+ * щоб агент прочитав документацію/README/чейнджлог.
+ * @param {string} html сирий html
+ * @returns {string} текст
+ */
+export function htmlToText(html) {
+  let text = html
+  for (const tag of ['script', 'style', 'noscript']) text = stripTagBlocks(text, tag)
+  text = text.replaceAll(BLOCK_CLOSE_TAGS, '\n').replaceAll(BR_HR_TAGS, '\n')
+  return stripTags(text)
+    .replaceAll('&nbsp;', ' ')
+    .replaceAll('&amp;', '&')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&#39;', "'")
+    .replaceAll(SPACES, ' ')
+    .replaceAll(BLANK_LINES, '\n\n')
+    .trim()
+}
+
+/**
+ * Fetch з SSRF-guard на кожному redirect-hop-і, таймаутом і лімітом розміру.
+ * @param {string} rawUrl цільовий URL
+ * @param {{ timeoutMs?: number, maxChars?: number, fetchImpl?: typeof fetch }} [opts] параметри
+ * @returns {Promise<{ url: string, status: number, contentType: string, text: string, truncated: boolean }>} сторінка текстом
+ */
+export async function fetchPage(
+  rawUrl,
+  { timeoutMs = FETCH_TIMEOUT_MS, maxChars = DEFAULT_MAX_CHARS, fetchImpl = fetch } = {}
+) {
+  let url = assertPublicHttpUrl(rawUrl)
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    let response
+    for (let hop = 0; ; hop++) {
+      response = await fetchImpl(url, { redirect: 'manual', signal: controller.signal })
+      if (response.status < 300 || response.status >= 400) break
+      if (hop >= MAX_REDIRECTS) throw new Error(`занадто багато redirect-ів (> ${MAX_REDIRECTS})`)
+      const location = response.headers.get('location')
+      if (!location) throw new Error(`redirect ${response.status} без Location`)
+      url = assertPublicHttpUrl(new URL(location, url).href)
+    }
+    const contentType = response.headers.get('content-type') ?? ''
+    const raw = await response.text()
+    const text = HTML_CONTENT_TYPE.test(contentType) ? htmlToText(raw) : raw
+    return {
+      url: url.href,
+      status: response.status,
+      contentType,
+      text: text.slice(0, maxChars),
+      truncated: text.length > maxChars
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Search-адаптери: нормалізують відповідь до [{title, url, snippet}]. */
+const PROVIDERS = {
+  brave: {
+    keyVar: 'BRAVE_API_KEY',
+    async search(query, count, key, fetchImpl) {
+      const u = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`
+      const r = await fetchImpl(u, { headers: { 'X-Subscription-Token': key, Accept: 'application/json' } })
+      if (!r.ok) throw new Error(`brave: HTTP ${r.status}`)
+      const data = await r.json()
+      return (data.web?.results ?? []).map(x => ({ title: x.title, url: x.url, snippet: x.description ?? '' }))
+    }
+  },
+  tavily: {
+    keyVar: 'TAVILY_API_KEY',
+    async search(query, count, key, fetchImpl) {
+      const r = await fetchImpl('https://api.tavily.com/search', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
+        body: JSON.stringify({ query, max_results: count })
+      })
+      if (!r.ok) throw new Error(`tavily: HTTP ${r.status}`)
+      const data = await r.json()
+      return (data.results ?? []).map(x => ({ title: x.title, url: x.url, snippet: x.content ?? '' }))
+    }
+  },
+  exa: {
+    keyVar: 'EXA_API_KEY',
+    async search(query, count, key, fetchImpl) {
+      const r = await fetchImpl('https://api.exa.ai/search', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-api-key': key },
+        body: JSON.stringify({ query, numResults: count, contents: { text: { maxCharacters: 500 } } })
+      })
+      if (!r.ok) throw new Error(`exa: HTTP ${r.status}`)
+      const data = await r.json()
+      return (data.results ?? []).map(x => ({ title: x.title ?? x.url, url: x.url, snippet: x.text ?? '' }))
+    }
+  }
+}
+
+/**
+ * Обирає search-провайдера: явний `N_LLM_SEARCH_PROVIDER` або перший наявний ключ.
+ * @param {Record<string, string|undefined>} env середовище
+ * @returns {{ name: string, key: string }|null} провайдер+ключ або null (жодного)
+ */
+export function resolveSearchProvider(env = processEnv) {
+  const wanted = env.N_LLM_SEARCH_PROVIDER
+  if (wanted) {
+    const p = PROVIDERS[wanted]
+    const key = p ? env[p.keyVar] : undefined
+    return p && key ? { name: wanted, key } : null
+  }
+  for (const [name, p] of Object.entries(PROVIDERS)) {
+    if (env[p.keyVar]) return { name, key: env[p.keyVar] }
+  }
+  return null
+}
+
+/**
+ * Структурована текстова відмова tool-виклику.
+ * @param {object} payload обʼєкт з `error`
+ * @returns {{ content: Array<{ type: string, text: string }>, details: object }} tool-результат
+ */
+function toolFail(payload) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload) }], details: {} }
+}
+
+/**
+ * Успішний текстовий tool-результат.
+ * @param {string} text текст відповіді
+ * @returns {{ content: Array<{ type: string, text: string }>, details: object }} tool-результат
+ */
+function toolOk(text) {
+  return { content: [{ type: 'text', text }], details: {} }
+}
+
+/**
+ * Фабрика пари pi-tools `web_search`/`web_fetch`.
+ * @param {{ defineTool: (def: object) => object,
+ *   deps?: { env?: Record<string, string|undefined>, fetchImpl?: typeof fetch } }} args контекст:
+ *   pi defineTool + інжекції env/fetch для тестів
+ * @returns {{ searchTool: object, fetchTool: object }} tool-дефініції для customTools
+ */
+export function createWebTools({ defineTool, deps = {} }) {
+  const env = deps.env ?? processEnv
+  const fetchImpl = deps.fetchImpl ?? fetch
+
+  const searchTool = defineTool({
+    name: 'web_search',
+    label: 'Web search',
+    description: 'Search the web. Returns a JSON list of {title, url, snippet}. Use web_fetch to read a result page.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'search query' },
+        count: { type: 'number', description: `max results (default ${DEFAULT_SEARCH_COUNT})` }
+      },
+      required: ['query']
+    },
+    execute: async (_id, { query, count }) => {
+      const provider = resolveSearchProvider(env)
+      if (!provider) {
+        return toolFail({
+          error:
+            'search-провайдер не сконфігуровано: потрібен BRAVE_API_KEY / TAVILY_API_KEY / EXA_API_KEY (опц. N_LLM_SEARCH_PROVIDER)'
+        })
+      }
+      try {
+        const results = await PROVIDERS[provider.name].search(
+          query,
+          count ?? DEFAULT_SEARCH_COUNT,
+          provider.key,
+          fetchImpl
+        )
+        return toolOk(JSON.stringify({ provider: provider.name, results }))
+      } catch (error) {
+        return toolFail({ error: `web_search: ${error.message}` })
+      }
+    }
+  })
+
+  const fetchTool = defineTool({
+    name: 'web_fetch',
+    label: 'Web fetch',
+    description:
+      'Fetch a public http(s) URL and return its text content (html is stripped to text). Truncated to a size limit.',
+    parameters: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'absolute http(s) URL' },
+        maxChars: { type: 'number', description: `truncate limit (default ${DEFAULT_MAX_CHARS})` }
+      },
+      required: ['url']
+    },
+    execute: async (_id, { url, maxChars }) => {
+      try {
+        const page = await fetchPage(url, { maxChars: maxChars ?? DEFAULT_MAX_CHARS, fetchImpl })
+        return toolOk(JSON.stringify(page))
+      } catch (error) {
+        return toolFail({ error: `web_fetch: ${error.message}` })
+      }
+    }
+  })
+
+  return { searchTool, fetchTool }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/llm-lib",
-  "version": "2.2.1",
+  "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",