@7n/llm-lib 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [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/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/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/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.3.0",
   "description": "Тонкий шар роботи з LLM (локальні omlx + хмарні провайдери) поверх pi: model tiers, one-shot, agentic-раннери, write-guard, trace, telemetry, prompt-budget",
   "keywords": [
     "nitra",