@7n/llm-lib 2.6.1 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [2.7.0] - 2026-07-16
+
+### Added
+
+- `runAcpAgent`/`resolveModel`/`oneShotLocalCloud` (`@7n/llm-lib/acp`) — napi-міст до Rust-крейта `llm_cascade` (`llm-lib/crates/llm-cascade-napi`): ACP-виклик `cursor`/`codex`, каскад тирів і local/cloud chat-виклик в одному процесі, без повторної реалізації протоколу в JS
+
+## [2.6.2] - 2026-07-14
+
+### Added
+
+- llm-cascade: файлові доки (docs/*.md) для src і examples — 7 нових док за стилем doc-files
+
 ## [2.6.1] - 2026-07-13
 
 ### Changed

package/lib/acp.mjs

@@ -0,0 +1,28 @@
+/**
+ * ACP (Agent Client Protocol, Zed) — доступ до `cursor`/`codex` через
+ * особисту підписку (вже залогінений локально CLI), не API-ключ.
+ *
+ * Тонкий JS-клієнт до Rust-крейта `llm_cascade::acp` через napi FFI
+ * in-process (`llm-lib/crates/llm-cascade-napi`) — жодного власного
+ * ACP JSON-RPC/`ClientSideConnection` тут; уся протокольна логіка (спавн
+ * агента, `session/prompt`, автоапрув `session/request_permission`) живе
+ * в Rust, разом з watchdog-поведінкою на мертвий/незапущений дочірній процес.
+ *
+ * `claude` тут немає — Rust-крейт моделює лише `cursor`/`codex`
+ * (`AcpAgentKind`); deprecated `claude`-раннер лишається окремим
+ * JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
+ */
+import { loadNative } from './internal/native.mjs'
+
+/**
+ * Один виклик через ACP-агента з особистою підпискою.
+ * @param {'cursor' | 'codex'} kind провайдер
+ * @param {string} prompt промпт
+ * @param {string} cwd робочий каталог сесії агента (каталог проєкту-викликача)
+ * @param {{ native?: { oneShotAcp: (kind: string, prompt: string, cwd: string) => Promise<string> } }} [deps] інжект для тестів
+ * @returns {Promise<string>} повний текст відповіді до кінця ходу
+ */
+export function runAcpAgent(kind, prompt, cwd, deps = {}) {
+  const native = deps.native ?? loadNative()
+  return native.oneShotAcp(kind, prompt, cwd)
+}

package/lib/docs/acp.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: acp.mjs
+resource: llm-lib/lib/acp.mjs
+docgen:
+  crc: 5c32e90c
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл надає тонкий JS-доступ до `cursor` або `codex` через публічну `runAcpAgent`, покладаючись на вже авторизовану локальну CLI-сесію без API-ключів. Уся ACP-логіка живе в нативному Rust-шарі `llm_cascade::acp`, який викликається in-process через `napi FFI` у `llm-lib/crates/llm-cascade-napi`; тут немає власного `ClientSideConnection` чи JSON-RPC. Саме Rust запускає агента, обробляє `session/prompt`, автоматично погоджує `session/request_permission` і стежить за живістю дочірнього процесу. Крейт підтримує лише `cursor`/`codex`; `claude`-runner лишається окремим JS-шимом у `@7n/rules` (`npm/scripts/lib/acp-runner.mjs`).
+
+## Поведінка
+
+1. `runAcpAgent` запускає один ACP-хід для `cursor` або `codex` через вже авторизовану локальну CLI-сесію, без API-ключів.
+2. Вона звертається до нативного Rust-шару `llm_cascade::acp`, який бере на себе весь протокол взаємодії: старт агента, обмін `session/prompt`, автоапрув запитів на дозвіл і контроль живості дочірнього процесу.
+3. Вона передає робочий каталог поточного проєкту як контекст сесії, щоб агент працював у межах каталогу викликача.
+4. Вона повертає повний текст відповіді агента за один хід.
+5. Вона не виконує власну протокольну логіку, не працює з `claude`, і не покладається на `ClientSideConnection`; підтримка `claude` живе окремо в JS-шимі `npm/scripts/lib/acp-runner.mjs`.
+
+## Публічний API
+
+- runAcpAgent — запускає один запит через ACP-агента з власною підпискою
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/lib/docs/index.md

@@ -4,22 +4,21 @@ title: llm-lib/lib
 resource: llm-lib/lib/
 ---
 
-# llm-lib/lib
-
-Публічні модулі пакета `@7n/llm-lib` (див. README пакета; спека
-docs/specs/2026-07-05-llm-lib-extraction-spec.md).
-
 | Файл                                      | Тип       |
 | ----------------------------------------- | --------- |
+| [acp.mjs](acp.md)                         | JS Module |
 | [agent-fix.mjs](agent-fix.md)             | JS Module |
 | [agent-skill.mjs](agent-skill.md)         | JS Module |
+| [anchored-edit.mjs](anchored-edit.md)     | JS Module |
 | [body-capture.mjs](body-capture.md)       | JS Module |
 | [chain.mjs](chain.md)                     | JS Module |
 | [chains-report.mjs](chains-report.md)     | JS Module |
+| [harness.mjs](harness.md)                 | JS Module |
 | [model-tiers.mjs](model-tiers.md)         | JS Module |
 | [one-shot.mjs](one-shot.md)               | JS Module |
 | [prompt-budget.mjs](prompt-budget.md)     | JS Module |
 | [telemetry-store.mjs](telemetry-store.md) | JS Module |
 | [trace.mjs](trace.md)                     | JS Module |
+| [web-tools.mjs](web-tools.md)             | JS Module |
 | [with-timeout.mjs](with-timeout.md)       | JS Module |
 | [write-guard.mjs](write-guard.md)         | JS Module |

package/lib/internal/docs/index.md

@@ -12,4 +12,5 @@ resource: llm-lib/lib/internal/
 | [compress-context.mjs](compress-context.md)         | JS Module |
 | [max-tokens.mjs](max-tokens.md)                     | JS Module |
 | [memory-guard.mjs](memory-guard.md)                 | JS Module |
+| [native.mjs](native.md)                             | JS Module |
 | [registry.mjs](registry.md)                         | JS Module |

package/lib/internal/docs/native.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: native.mjs
+resource: llm-lib/lib/internal/native.mjs
+docgen:
+  crc: 205418d5
+  model: openai-codex/gpt-5.5
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл знаходить і завантажує native-аддон `llm-cascade`, щоб JavaScript-код використовував Rust-ядро через napi-артефакт. `resolveNativeAddon` визначає шлях за єдиним порядком: явний override `N_LLM_LIB_NATIVE_ADDON`, platform-підпакет `@7n/llm-lib-<platform>-<arch>` з артефактом `llm-cascade-napi.<triple>.node`, dev-fallback у `target/release|debug/` після `cargo build -p llm-cascade-napi` або вивід у `llm-lib/crates/llm-cascade-napi/`. `loadNative` завантажує знайдений аддон через `process.dlopen` і кешує результат у межах процесу. На непідтриманих платформах запуск зупиняється зрозумілою помилкою без JS-fallback.
+
+## Поведінка
+
+- `resolveNativeAddon` визначає шлях до native-аддона `llm-cascade`: спершу бере явний override, далі шукає platform-підпакет, потім локальні dev-збірки; для непідтриманої або незібраної платформи завершується зрозумілою помилкою без JS-fallback.
+- `loadNative` завантажує native-аддон один раз за процес і повертає закешовані exports для повторних викликів.
+
+## Публічний API
+
+- resolveNativeAddon — знаходить файл native addon `llm-cascade` для поточного середовища або тестових підмін.
+- loadNative — повертає native addon із кешу, щоб завантажувати його лише один раз за час роботи процесу.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/lib/internal/native.mjs

@@ -0,0 +1,125 @@
+/**
+ * Loader napi-аддона `llm-cascade` (Rust-ядро `llm-lib/crates/llm-cascade-napi`
+ * → `llm-cascade`) — за зразком `mt/npm/lib/core/native.mjs`.
+ *
+ * Порядок пошуку:
+ *   1. N_LLM_LIB_NATIVE_ADDON — явний override шляху до аддона (dev / CI / тести).
+ *   2. Platform-підпакет `@7n/llm-lib-<platform>-<arch>` (napi-артефакт
+ *      `llm-cascade-napi.<triple>.node`).
+ *   3. Dev-fallback: `<repoRoot>/target/release|debug/` (сирий cdylib з
+ *      `cargo build -p llm-cascade-napi`) та вивід `napi build` у
+ *      `llm-lib/crates/llm-cascade-napi/`.
+ *   4. Інакше — зрозуміла помилка з підказкою.
+ *
+ * Аддон завантажується через `process.dlopen` — працює і для `.node`, і для
+ * сирих cdylib (`.dylib`/`.so`). Результат кешується (одне завантаження на процес).
+ * Без JS-fallback на неоголошеній платформі — hard error, свідома межа v1
+ * (darwin-arm64, linux-x64), не регресія.
+ */
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import process, { arch as osArch, env as procEnv, platform as osPlatform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const require = createRequire(import.meta.url)
+const HERE = dirname(fileURLToPath(import.meta.url))
+/** Корінь репо: llm-lib/lib/internal → up 3. */
+const REPO_ROOT = join(HERE, '..', '..', '..')
+
+/** Підтримувані platform-arch → napi-суфікс артефакта (v1: darwin-arm64, linux-x64). */
+const NAPI_SUFFIXES = {
+  'darwin-arm64': 'darwin-arm64',
+  'linux-x64': 'linux-x64-gnu'
+}
+
+/** @type {Record<string, unknown> | null} */
+let cached = null
+
+/**
+ * Завантажує аддон за шляхом через process.dlopen.
+ * @param {string} p шлях до .node / .dylib / .so
+ * @returns {Record<string, unknown>} exports аддона
+ */
+function dlopenAddon(p) {
+  const mod = { exports: {} }
+  process.dlopen(mod, p)
+  return mod.exports
+}
+
+/**
+ * Ім'я cdylib-файлу для платформи (вивід `cargo build -p llm-cascade-napi`).
+ * @param {string} platform process.platform
+ * @returns {string} ім'я бібліотеки
+ */
+function cdylibName(platform) {
+  return platform === 'darwin' ? 'libllm_cascade_napi.dylib' : 'libllm_cascade_napi.so'
+}
+
+/**
+ * Резолвить шлях до napi-аддона `llm-cascade`.
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   platform?: string,
+ *   arch?: string,
+ *   existsSync?: (p: string) => boolean,
+ *   requireResolve?: (id: string) => string,
+ *   repoRoot?: string
+ * }} [deps] ін'єкції для тестів
+ * @returns {string} шлях до файлу аддона
+ */
+export function resolveNativeAddon(deps = {}) {
+  const env = deps.env ?? procEnv
+  const platform = deps.platform ?? osPlatform
+  const arch = deps.arch ?? osArch
+  const exists = deps.existsSync ?? existsSync
+  const requireResolve = deps.requireResolve ?? (id => require.resolve(id))
+  const repoRoot = deps.repoRoot ?? REPO_ROOT
+
+  // 1. Явний override.
+  const override = env.N_LLM_LIB_NATIVE_ADDON
+  if (override) return override
+
+  const key = `${platform}-${arch}`
+  const suffix = NAPI_SUFFIXES[key]
+
+  // 2. Platform-підпакет.
+  if (suffix) {
+    try {
+      return requireResolve(`@7n/llm-lib-${key}/llm-cascade-napi.${suffix}.node`)
+    } catch {
+      // не встановлено — пробуємо dev-fallback
+    }
+  }
+
+  // 3. Dev-fallback: cargo-збірка (сирий cdylib) або вивід napi build.
+  const candidates = Array.from(['release', 'debug'], profile =>
+    join(repoRoot, 'target', profile, cdylibName(platform))
+  )
+  if (suffix) {
+    candidates.push(join(repoRoot, 'llm-lib', 'crates', 'llm-cascade-napi', `llm-cascade-napi.${suffix}.node`))
+  }
+  for (const candidate of candidates) {
+    if (exists(candidate)) return candidate
+  }
+
+  // 4. Помилка з підказкою.
+  throw new Error(
+    `llm-cascade native addon: немає збірки для "${key}". ` +
+      `Постав N_LLM_LIB_NATIVE_ADDON=/шлях/до/аддона, додай підпакет @7n/llm-lib-${key}, ` +
+      `або збери локально: cargo build --release -p llm-cascade-napi`
+  )
+}
+
+/**
+ * Кешований доступ до аддона (одне завантаження на процес).
+ * @param {{ resolve?: () => string, dlopen?: (p: string) => Record<string, unknown> }} [deps] ін'єкції
+ * @returns {Record<string, unknown>} exports аддона (oneShotAcp, resolveModel, oneShotLocalCloud)
+ */
+export function loadNative(deps = {}) {
+  if (cached === null) {
+    const path = (deps.resolve ?? resolveNativeAddon)()
+    cached = (deps.dlopen ?? dlopenAddon)(path)
+  }
+  return cached
+}

package/package.json

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