@7n/tauri-components 0.8.0 → 0.9.0

package/src/core/acp-kit.js

@@ -0,0 +1,260 @@
+import * as acpAgent from './acp-agent.js'
+import { createDispatch } from './dispatch.js'
+import { classify, DEFAULT_ACTOR_TIERS } from './scope.js'
+
+// createAcpAgentKit binds an app's catalog + journal to the ACP execution
+// engine — the ACP-flavored sibling of createAgentKit (agent-kit.js), added
+// alongside it so existing consumers keep working on the old omlx/runAgent
+// path while migrating at their own pace (see SPEC / plan for the sequencing).
+//
+// The two engines differ in where tool dispatch happens: runAgent() drove its
+// own tool-calling loop and dispatched synchronously inside handleRequest.
+// Here the ACP agent process drives its OWN loop and calls domain tools
+// through the Rust-side MCP bridge — so dispatch is triggered by a STANDING
+// listener on `acp://mcp-tool-call`, not by anything in request()/respond().
+// Every such call is tier-classified as an `{kind:'agent'}` actor, since by
+// construction only an autonomous agent process can reach the bridge.
+//
+// Scope: one active session/request at a time, matching how AgentDialog is
+// actually used today (a single live conversation). A tool call or permission
+// request always attaches its `needs_approval` state to whichever journal
+// request is currently active — concurrent sessions would need per-session
+// routing, which isn't attempted here.
+
+const AGENT_ACTOR = { kind: 'agent', id: 'acp' }
+const QUESTION_RE = /\?\s*$/
+
+/**
+ * @param {string} text candidate text
+ * @returns {boolean} true when text ends with a question mark
+ */
+function isQuestion(text) {
+  return typeof text === 'string' && QUESTION_RE.test(text.trim())
+}
+
+/**
+ * Derive the structured result fields from a runAcpTurn() result.
+ * @param {{content: string, stopped?: string}} turn runAcpTurn result
+ * @returns {{status: string, summary: string|null, question: string|null}} fields
+ */
+function finalizeTurn(turn) {
+  const question = isQuestion(turn.content) ? turn.content : null
+  let status = 'done'
+  if (turn.stopped === 'max_steps' || turn.stopped === 'refusal') status = 'partial'
+  else if (turn.stopped === 'cancelled') status = 'partial'
+  else if (question) status = 'needs_clarification'
+  return { status, summary: question ? null : (turn.content || null), question }
+}
+
+/**
+ * @param {object} config kit configuration
+ * @param {object[]} config.catalog tool definitions (required)
+ * @param {object} config.journal journal store { create, load, update, list }
+ * @param {(tool: object, input: object) => unknown} [config.transport] backend runner for domain tools; omit for a chat-only kit (no domain MCP tools)
+ * @param {Record<string, number>} [config.actorTiers] max executable tier rank per actor kind
+ * @param {object} [config.deps] injectable `acp-agent.js` functions (tests only — defaults to the real module)
+ * @returns {{request: Function, respond: Function, approve: Function}} bound kit
+ */
+export function createAcpAgentKit({ catalog, journal, transport, actorTiers = DEFAULT_ACTOR_TIERS, deps = acpAgent } = {}) {
+  if (!Array.isArray(catalog)) throw new Error('createAcpAgentKit: catalog (array) is required')
+
+  const dispatch = transport ? createDispatch(catalog, transport) : null
+  let activeSessionKey = null
+  let activeRequestId = null
+  let listening = false
+
+  /**
+   * Resolve one pending MCP tools/call per the tier decision. Called once per
+   * `acp://mcp-tool-call` event.
+   * @param {{requestId: string, tool: string, input: object}} payload event payload
+   * @returns {Promise<void>} resolves once the bridge has an answer
+   */
+  async function handleToolCall({ requestId, tool, input }) {
+    if (!dispatch) {
+      await deps.respondAcpToolCall(requestId, { ok: false, error: { code: 'forbidden', message: 'No transport configured.' } })
+      return
+    }
+    const decision = classify(catalog, actorTiers, AGENT_ACTOR, tool)
+    if (decision === 'deny') {
+      await deps.respondAcpToolCall(requestId, { ok: false, error: { code: 'forbidden', message: `Tool "${tool}" is not allowed.` } })
+      return
+    }
+    if (decision === 'approval') {
+      if (activeRequestId) {
+        await journal.update(activeRequestId, { status: 'needs_approval', pendingApproval: { kind: 'mcp', requestId, tool, input } })
+      }
+      return // acp_mcp_tool_result comes later, from approve()
+    }
+    await deps.respondAcpToolCall(requestId, await dispatch(tool, input))
+  }
+
+  /**
+   * Mirror a native ACP `session/request_permission` into the same
+   * `pendingApproval` shape as an MCP tool-call pause, so `AuditDialog` only
+   * has to understand one contract.
+   * @param {{requestId: string, toolCall: object, options: {optionId: string, name: string, kind: string}[]}} payload event payload
+   * @returns {Promise<void>} resolves once the journal is updated
+   */
+  async function handlePermissionRequest(payload) {
+    if (!activeRequestId) return
+    await journal.update(activeRequestId, { status: 'needs_approval', pendingApproval: { kind: 'acp', ...payload } })
+  }
+
+  /**
+   * Start listening for domain tool calls and native permission requests —
+   * lazy, once per kit, since it applies to every session this kit drives.
+   * @returns {Promise<void>} resolves once both listeners are attached
+   */
+  async function ensureListening() {
+    if (listening) return
+    listening = true
+    await deps.onAcpToolCall(handleToolCall)
+    await deps.onAcpPermissionRequest(handlePermissionRequest)
+  }
+
+  /**
+   * Run one turn, journal the result, and reset `pendingApproval`. Callers
+   * must set `activeRequestId` themselves *before* starting the turn — a
+   * tool-call/permission-request can arrive (and needs to see the right id)
+   * while the turn's own promise is still pending, so setting it here as a
+   * side effect of awaiting would be too late.
+   * @param {string} requestId journal record id
+   * @param {object[]} baseActions actions already recorded for this request
+   * @param {Promise<object>} turnPromise the in-flight `runAcpTurn` call
+   * @returns {Promise<object>} structured result envelope
+   */
+  async function runAndJournal(requestId, baseActions, turnPromise) {
+    let turn
+    try {
+      turn = await turnPromise
+    }
+    catch (error) {
+      await journal.update(requestId, { status: 'failed', error: String(error?.message ?? error) })
+      return { requestId, status: 'failed', summary: null, actions: baseActions, question: null, pendingApproval: null }
+    }
+    const fields = finalizeTurn(turn)
+    const actions = [...baseActions, ...turn.trace]
+    await journal.update(requestId, { ...fields, messages: turn.messages, actions, pendingApproval: null })
+    return { requestId, ...fields, actions, pendingApproval: null }
+  }
+
+  return {
+    /**
+     * Start a new ACP-backed request: spawns the agent session and runs the
+     * first prompt turn.
+     * @param {{intent: string, agent: object}} opts `agent` is passed straight to `createAcpSession` (agentKind/command/args/env/cwd/…)
+     * @returns {Promise<object>} structured result envelope
+     */
+    async request({ intent, agent }) {
+      await ensureListening()
+      const id = await journal.create({ intent, actor: AGENT_ACTOR })
+      await journal.update(id, { status: 'running' })
+      const session = await deps.createAcpSession(agent)
+      activeSessionKey = session.sessionKey
+      activeRequestId = id
+      await journal.update(id, { acp: { agentKind: session.agentKind, sessionKey: session.sessionKey } })
+      return runAndJournal(id, [], deps.runAcpTurn({ sessionKey: activeSessionKey, text: intent }))
+    },
+
+    /**
+     * Continue the active session with a follow-up message.
+     * @param {{requestId: string, message: string}} opts resume parameters
+     * @returns {Promise<object>} updated result envelope
+     */
+    async respond({ requestId, message }) {
+      if (!activeSessionKey) {
+        return { requestId, status: 'failed', summary: null, actions: [], question: 'No active ACP session.', pendingApproval: null }
+      }
+      let record
+      try {
+        record = await journal.load(requestId)
+      }
+      catch {
+        return { requestId, status: 'failed', summary: null, actions: [], question: 'Request not found.', pendingApproval: null }
+      }
+      await journal.update(requestId, { status: 'running' })
+      activeRequestId = requestId
+      return runAndJournal(requestId, record.actions ?? [], deps.runAcpTurn({ sessionKey: activeSessionKey, text: message }))
+    },
+
+    /**
+     * Resolve a pending approval — either an MCP domain-tool call or a native
+     * ACP permission request, whichever is attached to this journal record.
+     * @param {{requestId: string, approve: boolean}} opts approval parameters
+     * @returns {Promise<object>} updated result envelope
+     */
+    async approve({ requestId, approve: decision }) {
+      let record
+      try {
+        record = await journal.load(requestId)
+      }
+      catch {
+        return { requestId, status: 'failed', summary: null, actions: [], question: 'Request not found.', pendingApproval: null }
+      }
+
+      const pending = record.pendingApproval
+      if (record.status !== 'needs_approval' || !pending) {
+        return { requestId, status: record.status, summary: record.summary, actions: record.actions ?? [], question: null, pendingApproval: null }
+      }
+
+      if (pending.kind === 'acp') return approveAcpPermission(deps, journal, requestId, record, pending, decision)
+      return approveMcpToolCall(deps, dispatch, journal, requestId, record, pending, decision)
+    },
+  }
+}
+
+/**
+ * Resolve a pending MCP domain-tool call (reject with a forbidden envelope,
+ * or dispatch and forward the real envelope) and unblock the agent.
+ *
+ * Deliberately does **not** declare a terminal `done`/`rejected` status: once
+ * we reply to the agent's `tools/call`, its turn keeps running in the
+ * background — the in-flight `request()`/`respond()` call's `runAndJournal`
+ * is the only thing that will observe how the turn actually concludes (it
+ * may make more tool calls, or answer differently than a flat "done" would
+ * suggest), so it's the sole writer of the final journal state. This also
+ * means the old "retry a failed dispatch" UX doesn't carry over: once the
+ * agent has been told a tool call failed, it has already moved on.
+ * @param {object} deps injected acp-agent.js functions
+ * @param {Function} dispatch bound `createDispatch` result
+ * @param {object} journal journal store
+ * @param {string} requestId journal record id
+ * @param {object} record loaded journal record
+ * @param {{requestId: string, tool: string, input: object}} pending the paused MCP call
+ * @param {boolean} decision approve (true) or reject (false)
+ * @returns {Promise<object>} immediate (non-terminal) result envelope
+ */
+async function approveMcpToolCall(deps, dispatch, journal, requestId, record, pending, decision) {
+  const envelope = decision
+    ? await dispatch(pending.tool, pending.input)
+    : { ok: false, error: { code: 'forbidden', message: 'Rejected by human.' } }
+  await deps.respondAcpToolCall(pending.requestId, envelope)
+
+  const actions = [...(record.actions ?? []), { tool: pending.tool, input: pending.input, envelope }]
+  await journal.update(requestId, { status: 'running', actions, pendingApproval: null })
+  return { requestId, status: 'running', summary: null, actions, question: null, pendingApproval: null }
+}
+
+/**
+ * Resolve a native ACP `session/request_permission` by selecting the
+ * matching allow/reject option (`kind` from `PermissionOptionView`, see
+ * `tauri-plugin-agent/src/acp/mod.rs`) and unblock the agent. Falls back to
+ * the first option if none of the requested kind is offered. Same
+ * non-terminal-status rule as `approveMcpToolCall` — the agent's turn is
+ * still running.
+ * @param {object} deps injected acp-agent.js functions
+ * @param {object} journal journal store
+ * @param {string} requestId journal record id
+ * @param {object} record loaded journal record
+ * @param {{requestId: string, options: {optionId: string, kind: string}[]}} pending the paused permission request
+ * @param {boolean} decision approve (true) or reject (false)
+ * @returns {Promise<object>} immediate (non-terminal) result envelope
+ */
+async function approveAcpPermission(deps, journal, requestId, record, pending, decision) {
+  const wantPrefix = decision ? 'allow' : 'reject'
+  const option = pending.options?.find(o => o.kind?.startsWith(wantPrefix)) ?? pending.options?.[0]
+  await deps.respondAcpPermission(pending.requestId, option?.optionId)
+
+  await journal.update(requestId, { status: 'running', pendingApproval: null })
+  return { requestId, status: 'running', summary: null, actions: record.actions ?? [], question: null, pendingApproval: null }
+}

package/src/core/docs/acp-agent.md

@@ -0,0 +1,43 @@
+---
+docgen:
+  source: npm/src/core/acp-agent.js
+  crc: e30fb954
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# acp-agent.js
+
+## Огляд
+
+Модуль керує життєвим циклом сесій агента ACP. Він дозволяє ініціалізувати сесії за допомогою `createAcpSession`, виконувати ходи промпта через `runAcpTurn` та скасовувати сесії за допомогою `cancelAcpSession`. Модуль встановлює мережевий зв'язок через http://127.0.0.1:54321/ та ініціалізує MCP-міст за допомогою `startAcpMcpBridge`. Він реєструє інструменти та обробляє запити на виклики інструментів через `onAcpToolCall` та відповіді на них через `respondAcpToolCall`. Модуль також обробляє запити на дозволи через `onAcpPermissionRequest` та надає відповіді за допомогою `respondAcpPermission`. Модуль надає конфігурацію типу агента за допомогою `acpConfig`. Усі помилки перехоплюються (fail-safe), і винятки не викидаються назовні.
+
+## Поведінка
+
+createAcpSession запускає підпроцес агента ACP та ініціалізує його сесію, повертаючи ключ сесії.
+runAcpTurn виконує один хід промпта для існуючої сесії ACP, потоково передаючи оновлення сесії.
+cancelAcpSession відсилає команду на скасування поточного промпт-ходу для сесії ACP.
+onAcpToolCall підписується на події виклику інструменту, ініційовані агентом через MCP-міст.
+respondAcpToolCall вирішує очікуваний виклик інструменту, надаючи результат агенту.
+onAcpPermissionRequest підписується на запити дозволу від агента, наприклад, на доступ до файлової системи.
+respondAcpPermission вирішує очікуваний запит дозволу, обираючи один із запропонованих варіантів.
+startAcpMcpBridge реєструє каталог інструментів цього застосунку в доменному MCP-міст та запускає його, повертаючи URL, наприклад, http://127.0.0.1:54321/.
+acpConfig зчитує за замовчуванням тип агента для машини.
+
+## Публічний API
+
+createAcpSession — Запускає підпроцес агента ACP та виконує ініціалізацію з'єднання, повертаючи ідентифікатор сесії.
+runAcpTurn — Виконує один раунд взаємодії з агентом у вже ініційованій сесії, передаючи оновлення сесії.
+cancelAcpSession — Змушує агента припинити поточний раунд взаємодії.
+onAcpToolCall — Підписується на виклик інструменту, який агент ініціював через MCP-міст, очікуючи на результат.
+respondAcpToolCall — Надає відповідь на очікуваний виклик інструменту, який був ініційований агентом.
+onAcpPermissionRequest — Підписується на запит дозволу від агента (наприклад, на виконання команд або редагування файлів).
+respondAcpPermission — Приймає рішення щодо запиту дозволу, ініційованого агентом.
+startAcpMcpBridge — Реєструє каталог інструментів цього застосунку в доменному MCP-міст і запускає його.
+acpConfig — Зчитує за замовчуванням тип агента для цієї машини з змінної середовища. Доступні дані можна переглянути за адресою http://127.0.0.1:54321/.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/core/docs/acp-kit.md

@@ -0,0 +1,50 @@
+---
+docgen:
+  source: npm/src/core/acp-kit.js
+  crc: caab4cf6
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# acp-kit.js
+
+## Огляд
+
+Модуль ініціалізує агента та керує життєвим циклом його запитів. Функція `createAcpAgentKit` створює агента на основі заданих компонентів. Модуль дозволяє розпочинати нові запити, продовжувати активні сесії або вирішувати відкладені питання, такі як виклики інструментів чи запити на дозвіл.
+
+## Поведінка
+
+1. Викликати createAcpAgentKit, надаючи каталог інструментів, сховище журналу та, за бажанням, транспортний механізм, набір рівнів акторів та залежності.
+2. При виклику createAcpAgentKit, якщо надано транспортний механізм, створюється механізм диспетчеризації.
+3. Викликати request, щоб розпочати новий запит:
+    а. Забезпечити активне прослуховування подій.
+    б. Створити новий запис у журналі з інформацією про намір та актора.
+    в. Оновити запис у журналі на статус "running".
+    г. Створити сесію агента.
+    д. Встановити ключ сесії та ідентифікатор запиту як активні.
+    е. Оновити запис у журналі з метаданими сесії.
+    ж. Виконати перший хід агента, використовуючи наданий текст наміру, і зафіксувати результат у журналі.
+4. Викликати respond, щоб продовжити активну сесію:
+    а. Перевірити наявність активної сесії.
+    б. Завантажити поточний запис із журналу.
+    в. Оновити запис у журналі на статус "running".
+    г. Встановити ідентифікатор запиту як активний.
+    г. Виконати наступний хід агента, використовуючи надане повідомлення, і зафіксувати результат у журналі.
+5. Викликати approve, щоб вирішити відкладене схвалення:
+    а. Завантажити відповідний запис із журналу.
+    б. Перевірити, чи запис перебуває у стані "needs_approval" та має відкладене схвалення.
+    в. Якщо відкладене схвалення є MCP-виклик інструменту, викликати approveMcpToolCall:
+        а. Виконати диспетчеризацію інструменту або створити відповідь про заборону.
+        б. Надіслати відповідь агенту про результат виклику інструменту.
+        в. Оновити запис у журналі, додавши інформацію про виклик інструменту та скинувши відкладене схвалення.
+        в. Повернути результат, що вказує на статус "running".
+    г. Якщо відкладене схвалення є запит на дозвіл ACP, викликати approveAcpPermission:
+        а. Знайти відповідний варіант дозвілу або обрати перший варіант.
+        б. Надіслати відповідь агенту з обраним ідентифікатором варіанта.
+        в. Оновити запис у журналі, скинувши відкладене схвалення.
+        в. Повернути результат, що вказує на статус "running".
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/src/core/docs/agent-handler.md

@@ -0,0 +1,31 @@
+---
+docgen:
+  source: npm/src/core/agent-handler.js
+  crc: 8ef1230c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# agent-handler.js
+
+## Огляд
+
+Модуль керує життєвим циклом агентського запиту. Він ініціює запит через `handleRequest`, підтримує діалог з користувачем через `handleRespond` та реалізує логіку схвалення через `handleApprove`.
+
+## Поведінка
+
+handleRequest ініціює новий агентський запит, створює запис у журналі та запускає цикл агента.
+handleRespond продовжує розмову, використовуючи попередній стан запису та нове повідомлення користувача.
+handleApprove виконує або відхиляє заплановану деструктивну дію, якщо запис перебуває у стані очікування схвалення.
+
+## Публічний API
+
+handleRequest — Ініціює новий запит до агента.
+handleRespond — Продовжує діалог, надаючи відповідь або уточнення.
+handleApprove — Підтверджує (або відхиляє) заплановану руйнівну дію, виконуючи її з дозволу користувача.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/core/docs/agent-kit.md

@@ -0,0 +1,25 @@
+---
+docgen:
+  source: npm/src/core/agent-kit.js
+  crc: 27461b4b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# agent-kit.js
+
+## Огляд
+
+Цей модуль відповідає за ініціалізацію та конфігурування набору інструментів для агента. Функція `createAgentKit` створює об'єкт, що містить необхідні методи та механізми для роботи агента, забезпечуючи його доступ до інструментів та системних налаштувань.
+
+## Поведінка
+
+1. Викликати `createAgentKit` для створення набору інструментів агента.
+2. Надати `createAgentKit` каталог інструментів.
+3. За бажанням надати системний підказку, транспортний механізм, сховище журналу, рівні акторів та інструмент для заземлення.
+4. Отримати об'єкт набору інструментів, що містить функції для диспетчеризації, класифікації, отримання маніфесту інструментів, створення запитів, відповідей та схвалення.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/src/core/docs/dispatch.md

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/src/core/dispatch.js
+  crc: 57a74200
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# dispatch.js
+
+## Огляд
+
+Модуль забезпечує валідацію вхідних даних та диспетчеризацію виконання інструментів. Функція `validateInput` перевіряє вхідні дані на відповідність визначеній схемі. Після успішної валідації функція `createDispatch` створює механізм виконання інструменту. Модуль гарантує перехоплення всіх помилок (fail-safe) та не генерує винятків назовні. Модуль не виконує операцій, що змінюють стан (не пише у ФС/БД).
+
+## Поведінка
+
+validateInput перевіряє вхідні дані на відповідність схемі інструменту та кастомному валідатору.
+createDispatch створює функцію, яка виконує інструмент після валідації вхідних даних, повертаючи обгортку з результатом або помилкою.
+
+## Публічний API
+
+validateInput — порівнює об'єкт вхідних даних зі схемою інструменту та користувацьким валідатором.
+createDispatch — створює функцію для відправки, прив'язану до каталогу та системи транспортування.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/core/docs/llm.md

@@ -0,0 +1,29 @@
+---
+docgen:
+  source: npm/src/core/llm.js
+  crc: 2f379651
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# llm.js
+
+## Огляд
+
+Модуль дозволяє ініціювати сеанс чату з мовною моделлю через мережевий ендпоінт http://127.0.0.1:10240/v1. Функціонал реалізується через публічні функції `runAgent` та `createOpenAiChat`. Код виконує виклик API та керує циклом виклику інструментів у контексті агента, доки модель не надасть фінальну відповідь або не буде перевищено ліміт кроків. Робота залежить від конфігурації, описаної у `response.json`.
+
+## Поведінка
+
+runAgent виконує цикл виклику інструментів, поки модель не надасть відповідь без виклику інструменту, або доки не буде досягнуто максимальної кількості кроків.
+createOpenAiChat створює функцію, яка викликає мережевий ендпоінт OpenAI-сумісного API (наприклад, http://127.0.0.1:10240/v1) для отримання відповіді моделі.
+
+## Публічний API
+
+runAgent — Запускає цикл виклику інструментів до моменту, коли модель надає відповідь без виклику інструменту. Може використовувати новий запит або продовжувати сесію на основі існуючої історії повідомлень.
+createOpenAiChat — Створює функцію для взаємодії з кінцевою точкою, сумісною з OpenAI (omlx).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/src/core/docs/manifest.md

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/src/core/manifest.js
+  crc: 0db5edce
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# manifest.js
+
+## Огляд
+
+Модуль реалізує функції для роботи зі специфікаціями інструментів. Він перетворює специфікації інструментів у формат JSON Schema. Модуль генерує повний маніфест інструментів у форматі OpenAI та створює спрощені списки інструментів, що містять їхні імена та описи.
+
+## Поведінка
+
+toJsonSchema перетворює специфікацію вхідних даних інструменту на об'єкт JSON Schema.
+toolManifest створює масив визначень інструментів у форматі OpenAI, фільтруючи їх за наданим предикатом.
+listTools створює компактний список інструментів, що містить лише їхні імена та короткі описи.
+
+## Публічний API
+
+toJsonSchema — перетворює опис вхідних даних інструменту на об'єкт JSON Schema.
+toolManifest — надає визначення інструментів для виклику функцій OpenAI, з можливістю фільтрації.
+listTools — виводить стислий перелік доступних інструментів (назва та короткий опис).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/src/core/docs/omlx-models.md

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/src/core/omlx-models.js
+  crc: 81a5dc3a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# omlx-models.js
+
+## Огляд
+
+Модуль надає публічні механізми для взаємодії з локально завантаженими моделями. Він дозволяє отримати повний список доступних моделей та вибрати конкретну модель із цього списку. Функціонал працює в режимі, що перехоплює помилки (fail-safe), і не здійснює запису у файлову систему чи бази даних. Робота модуля залежить від конфігурацій, зокрема `response.json`.
+
+## Поведінка
+
+listOmlxModels отримує список ідентифікаторів моделей, завантажених локальним сервером, або повертає порожній масив у разі будь-якої помилки.
+resolveModel обирає модель з наданого списку, надаючи пріоритет обраній моделі, або повертає першу доступну модель, якщо пріоритетна відсутня.
+
+## Публічний API
+
+listOmlxModels — отримує список доступних моделей.
+resolveModel — вибирає модель: обрану, якщо вона завантажена, інакше першу доступну, або порожній рядок.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/src/core/docs/resolve-omlx-base-url.md

@@ -0,0 +1,40 @@
+---
+docgen:
+  source: npm/src/core/resolve-omlx-base-url.js
+  crc: 36c282c7
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# resolve-omlx-base-url.js
+
+## Огляд
+
+Модуль визначає та надає базові URL для взаємодії з серверами omlx. Він експортує константи: DIRECT_OMLX_BASE_URL="http://127.0.0.1:8000/v1" для прямого доступу та PROXY_OMLX_BASE_URL="http://127.0.0.1:8088/v1" для проксі-доступу. Модуль звертається до мережі для визначення робочого URL, перевіряючи доступність проксі-сервера. Вибір URL кешується у межах прогону. При помилках мережевого доступу модуль перехоплює їх (fail-safe) і повертає порожнє значення замість кидання винятків. Модуль є лише для читання (не виконує операцій з ФС/БД).
+
+## Поведінка
+
+DIRECT_OMLX_BASE_URL: Надає базовий URL для прямого доступу до сервера omlx, який є http://127.0.0.1:8000/v1.
+PROXY_OMLX_BASE_URL: Надає базовий URL для доступу через проксі-сервер omlx, який є http://127.0.0.1:8088/v1.
+isDirectOmlxUrl: Перевіряє, чи вказаний URL є стандартним локальним сервером omlx (http://127.0.0.1:8000 або localhost:8000).
+resolveOmlxBaseUrl: Визначає ефективний базовий URL omlx, перевіряючи доступність проксі-сервера через зондування `/health`; у разі успіху повертає URL проксі, інакше — прямий URL.
+resolveOmlxBaseUrlCached: Визначає ефективний базовий URL omlx, використовуючи кешування для уникнення повторних зондувань протягом заданого часу життя (TTL).
+__resetOmlxBaseUrlCache: Очищає кеш результатів зондування базового URL omlx.
+
+## Публічний API
+
+DIRECT_OMLX_BASE_URL — Базовий URL для прямого доступу до локального OMLX сервера, що вказує на http://127.0.0.1:8000/v1.
+PROXY_OMLX_BASE_URL — Базовий URL для проксі-доступу до OMLX сервера, що вказує на http://127.0.0.1:8088/v1.
+isDirectOmlxUrl — Визначає, чи є URL основним локальним сервером OMLX, який не повинен бути перенаправлений через проксі.
+resolveOmlxBaseUrl — Перевіряє доступність проксі-сервера шляхом виконання GET-запиту до http://127.0.0.1:8088/v1; якщо відповідь успішна, використовується проксі, інакше — прямий URL.
+resolveOmlxBaseUrlCached — Виконує перевірку доступності проксі-сервера з кешуванням, щоб уникнути повторних перевірок при кожному виклику LLM.
+__resetOmlxBaseUrlCache — Очищає всі збережені результати перевірки доступності базового URL OMLX.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Кешує результати в межах одного прогону.

package/src/core/docs/scope.md

@@ -0,0 +1,32 @@
+---
+docgen:
+  source: npm/src/core/scope.js
+  crc: e3226974
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# scope.js
+
+## Огляд
+
+Модуль визначає та керує дозволами акторів на використання інструментів. Він встановлює рівні акторів за допомогою `DEFAULT_ACTOR_TIERS`, визначає доступні інструменти для кожного актора через `scopedToolNames` та надає маніфест дозволів за допомогою `scopedManifest`.
+
+## Поведінка
+
+DEFAULT_ACTOR_TIERS визначає максимальний рівень виконання для різних типів акторів.
+classify визначає, чи дозволено актору викликати інструмент, чи потрібне схвалення, чи заборонено.
+scopedManifest повертає перелік інструментів, які актор може виконати або для яких потрібне схвалення.
+scopedToolNames повертає список назв інструментів, які актор бачить.
+
+## Публічний API
+
+DEFAULT_ACTOR_TIERS — Визначає рівні доступу для акторів.
+classify — Визначає, до якого актора належить виклик інструменту.
+scopedManifest — Перелік інструментів, доступних актору для виконання або запиту дозволу.
+scopedToolNames — Список назв інструментів, видимих актору.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/src/core/docs/tools.md

@@ -0,0 +1,28 @@
+---
+docgen:
+  source: npm/src/core/tools.js
+  crc: 9fa4e875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+# tools.js
+
+## Огляд
+
+Модуль сканує заданий каталог для пошуку визначень інструментів. Він встановлює наявність інструменту за його ім'ям і повертає його визначення або `null`, якщо інструмент не знайдено.
+
+## Поведінка
+
+1. Визначає, чи існує інструмент у наданому каталозі, порівнюючи його ім'я з вказаним.
+2. Повертає визначення інструмента, якщо він знайдений.
+3. Повертає `null`, якщо інструмент не знайдено в каталозі.
+
+## Публічний API
+
+getTool — знаходить інструмент за його назвою у каталозі.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).