berimor 0.27.0 → 0.29.0

package/README.md

@@ -14,7 +14,7 @@
 [![npm](https://img.shields.io/npm/v/berimor?logo=npm&label=npm)](https://www.npmjs.com/package/berimor)
 [![CI](https://img.shields.io/github/actions/workflow/status/devpilgrin/berimor/ci.yml?branch=main&label=CI)](https://github.com/devpilgrin/berimor/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-850%20green-brightgreen)](#инфраструктура-проекта)
+[![Tests](https://img.shields.io/badge/tests-946%20green-brightgreen)](#инфраструктура-проекта)
 
 ![Rust](https://img.shields.io/badge/Rust-stable-DEA584?logo=rust&logoColor=white)
 ![WebAssembly](https://img.shields.io/badge/sandbox-Wasmtime-654FF0?logo=webassembly&logoColor=white)
@@ -65,15 +65,113 @@ Deny-таблица деструктивных операций не переи
 - **Скилы** (SKILL.md) — экспертные роли для чата: триггер — кодом (не моделью), потолок инструментов — фильтром диспетча.
 - **Субагенты** (agent.yaml) — вложенный агентный цикл с собственным бюджетом и журналом; права ребёнка = пересечение с правами родителя, расшириться нельзя. Вложенное порождение — только с явным `allow_spawn: true`, глубина ограничена кодом.
 - **Плагины** — изолированные процессы с ACL-манифестом и keyless-подписью sigstore: установка из доверенного списка с TOFU-подтверждением, как SSH.
-- **MCP** — внешние серверы инструментов по открытому протоколу Model Context Protocol (официальный Rust SDK rmcp, ADR-0023): подключаются секцией `[[mcp_servers]]` в конфиге, встают в общий диспетчер после встроенных инструментов и плагинов и проходят тот же capability-гейт, что и любой шаг процесса. Работает и в обратную сторону: Berimor может отдавать собственные инструменты по MCP.
+- **MCP** — внешние серверы инструментов по открытому протоколу Model Context Protocol (официальный Rust SDK rmcp, ADR-0023): подключаются секцией `[[mcp_servers]]` в конфиге, встают в общий диспетчер после встроенных инструментов и плагинов и проходят тот же capability-гейт, что и любой шаг процесса. Работает и в обратную сторону: Berimor может отдавать собственные инструменты по MCP. Курируемый список серверов с готовыми блоками конфига — [`docs/mcp-servers.md`](docs/mcp-servers.md).
 
 Всё это устанавливается одной командой — из каталога или **любого git-репозитория**: `berimor skill install code-review-ru --from https://github.com/...`.
 
+## Возможности
+
+### Встроенные инструменты
+
+Инструменты — встроенные в бинарник (не плагины), все вызовы проходят capability-гейт: **мутирующие** (помечены *) требуют подтверждения по режиму гейта, читающие исполняются без вопросов.
+
+| Группа | Инструменты | Что делают |
+|---|---|---|
+| Файлы | `files.read`, `files.list`, `files.write`*, `files.edit`* | чтение/листинг; запись целиком; точечная правка по строковому якорю (old_string → new_string, контроль уникальности) |
+| Поиск | `files.search`, `session.search` | regex по содержимому файлов (с номерами строк и контекстом) или glob по именам — `.git`/`target`/`node_modules` пропускаются; подстрока по лентам прошлых сессий с excerpt |
+| VCS | `vcs.git` | git status/diff/log/show — только чтение: хелперы репозитория (fsmonitor, внешний diff, textconv) отключены, произвольные флаги не принимаются |
+| Терминал | `terminal.exec`*, `terminal.start`*, `terminal.output`, `terminal.kill` | команда с таймаутом и капом вывода; фоновые процессы с опросом и остановкой (до 32 одновременно) |
+| Сеть | `http.fetch`, `web.search` | GET с капом тела и сетевым гейтом; поисковая выдача DuckDuckGo (заголовок/ссылка/сниппет) |
+| Память | `memory.search`, `memory.save` | поиск фактов семантической памяти; запись факта с дедупликацией — по умолчанию выключена (включается осознанно: `[memory] tool_writes = true`), секреты маскируются до записи |
+| Организация | `todo.read`, `todo.write`, `human.ask` | список задач сессии (хранится в `.berimor/todo.json`); вопрос пользователю прямо из агентного цикла |
+| Снапшоты | `snapshot.list`, `snapshot.restore`* | автоматически: перед каждой перезаписью файла его состояние сохраняется (ротация 50); list — метки и пути, restore — откат (сам тоже со снапшотом) |
+| Субагенты | `agents.run` | поручение вложенному агенту с пересечением прав |
+
+Сверх встроенных — инструменты плагинов и MCP-серверов (та же гейт-политика). Полный список в чате: стартовая строка «инструменты: …».
+
+### Меню чата (TUI)
+
+Наберите `/` — палитра покажет команды с описаниями на языке интерфейса и фильтрует по мере набора. Подменю работают по пробелу: `/config ` показывает продолжения.
+
+| Команда | Что делает |
+|---|---|
+| `/help` | список команд |
+| `/models` | провайдеры: список, `/models add` — мастер (пресеты → выбор → ключ/OAuth), удаление — через пикер с подтверждением |
+| `/skills`, `/agents` | навыки и субагенты (глобальные/проектные), навык — Enter на строке |
+| `/config` | **меню параметров**: показ эффективной конфигурации и пункт «Локаль интерфейса» (с текущим значением) → выбор языка из 8 (ru, en, de, fr, es, zh-CN, ja, ko). Сохраняется в локальный конфиг (`[ui]`), действует сразу. Шорткат: `/config locale ja` |
+| `/mouse` | переключатель мыши: захвачена — колесо листает журнал, клик по журналу даёт фокус прокрутки; отпущена — нативное выделение/копирование терминала (при захвате выделение — через Shift) |
+| `/copy` | последний ответ агента — в буфер обмена (wl-copy/xclip/xsel/pbcopy) |
+| `/clear`, `/exit` | очистка журнала диалога; выход |
+
+Остальное в интерфейсе: **модалки подтверждений** опасных действий (варианты «один раз / до конца сессии / для проекта» — выбор стрелками ←→↑↓, y/n — сразу); **вопросы агента** (`human.ask`) — модалка со свободным вводом, Enter — ответить, Esc — отказ; **многострочный ввод** — Alt+Enter переводит строку, поле растёт до трети экрана, вставка из буфера — одним событием; **мышь** — колесо и клик-фокус (см. `/mouse`).
+
+## Процессы: графовые агенты
+
+Основной «боевой» режим berimor — **процесс**: декларативный YAML-план, который исполняется как граф. Это тот же подход, что у «графовых агентов» (LangGraph и подобных): узлы — шаги, рёбра — переходы, состояние — разделяемый объект; отличие в том, что топология и маршрутизация у berimor детерминированы — **модель никогда не выбирает ветку**: она может предложить значение через строгий контракт, а маршрутизирует код (инвариант I1).
+
+**Узлы графа** (типы шагов процесса):
+
+| Узел | Назначение |
+|---|---|
+| `sequential` | обычный шаг — переход к следующему |
+| `tool` | вызов инструмента (аргументы — шаблоны из состояния) |
+| `llm_structured` | вызов модели со строгим контрактом ответа (JSON Schema — отклоняется до приёма) |
+| `codeact` | программа модели в WASM-песочнице (QuickJS, топливо, белый список вызовов) |
+| `agent_step` | свободный цикл «рассуждение → действие → наблюдение» как узел: `max_turns`, опционально самокритика и «предложи—выполни—проверь» |
+| `branch` | условные рёбра: `on` — поле состояния, `cases` — ветки по значениям |
+| `loop` | петля по условию |
+| `parallel` | параллельные ветви с join-барьером |
+| `human_gate` | пауза на человека: причина, таймаут, политика таймаута (fail/ветка/эскалация) |
+| `checkpoint` | явная точка восстановления |
+
+Журнал событий покрывает чекпоинтинг с запасом: любой прогон можно продолжить ровно с места обрыва и воспроизвести состояние на любой момент (replay).
+
+**Честная граница подхода** (по результатам независимого полевого тестирования 0.27.0): контракт проверяет **форму, не смысл** — `branch` маршрутизирует код, но по значению, которое предложила модель; доверие не устранено, а спущено на уровень «значение, по которому вычисляется маршрут». Семантически значимые маршруты прикрывайте дополнительно: правилами политики контракта (диапазоны/перечисления), шагом верификации у сильной модели или `human_gate`. Вторая граница — слабые (локальные) модели: строгий контракт простой формы они выдерживают, а внутренний протокол свободного цикла требует модели среднего класса и выше; сценарий «полностью локально» сегодня реален для `llm_structured`-шагов, не для `agent_step`.
+
+**Контракты из конфигурации** (0.28.0): свои контракты без форка и пересборки — секция `[[contracts]]` в конфиге с JSON Schema (inline `schema` или `schema_path`), дальше `llm_structured`/`codeact`/`agent_step` ссылаются на неё по имени наравне с кодовыми. Вывод модели валидируется по схеме (crate `jsonschema`), ошибка валидации уходит в промпт повтора — тот же цикл медиации. Ограничения: policy-правил (ссылки на состояние) и версий схем у конфиг-контрактов нет, `publishable` — весь объект, реестр читается при старте (смена конфига — новый запуск). Пример — [`fixtures/golden/processes/config-contracts/`](fixtures/golden/processes/config-contracts/).
+
+**Нормализатор формы хода** (0.29.0): слабые модели часто пишут «почти протокольный» ответ — плоскую форму `{"thought", "tool", "args"}`, `"action": "tool"` строкой, верхнеуровневый `reply` или оборванный на лимите токенов JSON. Известные формы достраиваются детерминированно до протокола ДО медиации (ремонт журналируется событием `agent_turn_normalized`; смысл по-прежнему решают валидация и гейт). Промпт хода дополнен парой few-shot примеров.
+
+**Графовые идиомы как процессы.** Классические паттерны (routing, prompt chaining, parallelization, orchestrator-workers, evaluator-optimizer) выражаются без нового кода: `llm_structured` пишет решение-маршрут в состояние → `branch` маршрутизирует по валидированному значению; evaluator-optimizer — это `loop` с вердиктом; orchestrator-workers — `parallel` + join. Примеры процессов — в [`fixtures/golden/processes/`](fixtures/golden/processes/).
+
+### Архитектура агента
+
+```mermaid
+flowchart TD
+    U["Пользователь / расписание / HTTP"] --> CLI["berimor CLI<br/>(chat · run · serve · daemon)"]
+    CLI --> PE["Process Engine<br/>граф процесса: branch · loop · parallel · join"]
+    CLI --> EX["Свободный цикл<br/>agent_step"]
+    PE --> MED["Mediation<br/>валидация контрактов"]
+    EX --> MED
+    MED --> GATE["Capability Gate<br/>deny-статика → jail → подтверждение"]
+    GATE --> TOOLS["Инструменты<br/>встроенные → плагины → MCP"]
+    PE --> J[("Журнал событий SQLite<br/>resume · replay · аудит")]
+    EX --> J
+    MED --> MEM[("Память: эпизодическая FTS5,<br/>семантическая, граф сущностей")]
+    PE --> POOL["Model Pool<br/>провайдеры · тиры · failover"]
+    EX --> POOL
+    POOL --> LLM["LLM: облачные и локальные"]
+```
+
+### Пример графа процесса (evaluator-optimizer)
+
+```mermaid
+flowchart LR
+    A["llm_structured:<br/>черновик"] --> B["llm_structured:<br/>оценка по контракту"]
+    B --> C{"branch on: verdict"}
+    C -->|"не годится"| A
+    C -->|"годится"| D["human_gate:<br/>публикация?"]
+    D --> E["tool: запись результата"]
+    E --> F["checkpoint"]
+```
+
+Модель предлагает `verdict` — но в `cases` попадёт только значение, прошедшее контракт; выбор ветки вычисляет код.
+
 ## Инфраструктура проекта
 
 **Rust-workspace по крейту на компонент** — Process Engine, Mediation, Executors, Memory, Capability, Model Pool, Actors, Tool Runtime, Context Engine, Eval, Storage. Гостевой WASM-модуль (`codeact-guest/`) живёт отдельным crate и закоммичен как готовый артефакт — обычная сборка не замедляется.
 
-**Дисциплина проверок.** Каждый релиз: `cargo fmt` + `clippy -D warnings` + `cargo test --workspace` (850 тестов: юнит, интеграционные, e2e через настоящий бинарник, золотые фикстуры процессов и вредоносных вводов). Критические компоненты проходят обязательное независимое ревью. Полный самостоятельный аудит (`docs/audit-2026-07-31.md`) — **все находки закрыты или осознанно задокументированы**.
+**Дисциплина проверок.** Каждый релиз: `cargo fmt` + `clippy -D warnings` + `cargo test --workspace` (946 тестов: юнит, интеграционные, e2e через настоящий бинарник, золотые фикстуры процессов и вредоносных вводов). Критические компоненты проходят обязательное независимое ревью. Полный самостоятельный аудит (`docs/audit-2026-07-31.md`) — **все находки закрыты или осознанно задокументированы**.
 
 **Supply chain как у взрослых.** Кросс-платформенные релизы (Linux x64/arm64, macOS arm64, Windows x64) с keyless-подписью cosign/sigstore — приватного ключа не существует нигде. Проверка: `berimor verify <архив>`. npm-публикация с provenance, SBOM (CycloneDX) в пайплайне, самообновление (`berimor self-update`) реализовано на примитивах Process Engine — тот же журнал и восстановление после сбоя, что у обычных процессов, а не ad hoc скрипт.
 
@@ -94,12 +192,12 @@ berimor --version
 
 ### Способ 2: готовый бинарник с GitHub
 
-Актуальные версии — на странице [релизов](https://github.com/devpilgrin/berimor/releases/latest). Ниже — команды для скачивания конкретной версии (замените `v0.19.0` на нужную, если вышла более новая).
+Актуальные версии — на странице [релизов](https://github.com/devpilgrin/berimor/releases/latest). Ниже — команды для скачивания; версия подставляется автоматически (последний выпуск).
 
 **Linux** (x64 или arm64):
 
 ```sh
-VERSION=v0.19.0
+VERSION=$(curl -s https://api.github.com/repos/devpilgrin/berimor/releases/latest | grep '"tag_name"' | cut -d '"' -f 4)
 ARCH=x64   # или arm64
 curl -LO "https://github.com/devpilgrin/berimor/releases/download/${VERSION}/berimor-${VERSION}-linux-${ARCH}.tar.gz"
 tar -xzf "berimor-${VERSION}-linux-${ARCH}.tar.gz"
@@ -111,7 +209,7 @@ berimor --version
 **macOS** (только Apple Silicon — M1/M2/M3 и новее; сборки под Intel пока не публикуются, для Intel-Mac — способ 3 ниже):
 
 ```sh
-VERSION=v0.19.0
+VERSION=$(curl -s https://api.github.com/repos/devpilgrin/berimor/releases/latest | grep '"tag_name"' | cut -d '"' -f 4)
 curl -LO "https://github.com/devpilgrin/berimor/releases/download/${VERSION}/berimor-${VERSION}-darwin-arm64.tar.gz"
 tar -xzf "berimor-${VERSION}-darwin-arm64.tar.gz"
 xattr -d com.apple.quarantine berimor   # бинарник пока не подписан Apple — иначе Gatekeeper откажется его запускать
@@ -123,7 +221,7 @@ berimor --version
 **Windows** (x64), PowerShell:
 
 ```powershell
-$Version = "v0.19.0"
+$Version = (Invoke-RestMethod "https://api.github.com/repos/devpilgrin/berimor/releases/latest").tag_name
 Invoke-WebRequest -Uri "https://github.com/devpilgrin/berimor/releases/download/$Version/berimor-$Version-win32-x64.zip" -OutFile berimor.zip
 Expand-Archive -Path berimor.zip -DestinationPath .
 .\berimor.exe --version
@@ -158,7 +256,7 @@ berimor          # = berimor chat: интерактивный диалог с а
 
 Детерминированные процессы (декларативный YAML-план со строгими контрактами — основной «боевой» режим): `berimor run <process.yaml>`. Примеры процессов и конфигураций — в [`fixtures/golden/processes/`](fixtures/golden/processes/) и [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
-Автоматизация поверх процессов: `berimor schedule add` + `berimor daemon` — исполнение процессов по расписанию; `berimor serve` — HTTP-сервис поверх run/schedule/sessions (с токеном, без анонимного доступа); `berimor sessions` — реестр живых сессий хоста; `berimor trace <инстанс>` — человекочитаемая трассировка журнала любого прогона.
+Автоматизация поверх процессов: `berimor schedule add` + `berimor daemon` — исполнение процессов по расписанию (у демона и HTTP-сервиса нет терминала: запрос подтверждения трактуется как отказ с диагностикой — для автоматизации мутирующих шагов используйте точечное автоподтверждение в `.berimor/allow` либо флаг `berimor run --non-interactive` / `BERIMOR_NON_INTERACTIVE=1` в своих скриптах); `berimor serve` — HTTP-сервис поверх run/schedule/sessions (с токеном, без анонимного доступа); `berimor sessions` — реестр живых сессий хоста; `berimor trace <инстанс>` — человекочитаемая трассировка журнала любого прогона.
 
 Расширения одной командой:
 

package/checksums.json

@@ -1,6 +1,6 @@
 {
-  "berimor-v0.27.0-darwin-arm64.tar.gz": "b9fed6c4ae2cdbb96da9bdf9143d2be07fd5aa6a0a0aa2dbf8d56b78a0693447",
-  "berimor-v0.27.0-linux-arm64.tar.gz": "64c99128d943f40f40c9eda307abfd2cce410ed3eb81c0ed420e3194658dbdae",
-  "berimor-v0.27.0-linux-x64.tar.gz": "a9a3ed07522507efe3b2e394ddec5bb76f4f6d494bb9b452084121627301cfcb",
-  "berimor-v0.27.0-win32-x64.zip": "392f678714be0c3bb1ca92dee497eae1588740feaaec2eeb9b3a85fc248973e8"
+  "berimor-v0.29.0-darwin-arm64.tar.gz": "97be78f7b0aa90fb50bbbf923a8faad5383b4579f1feffc021984d6450c0eebe",
+  "berimor-v0.29.0-linux-arm64.tar.gz": "ac4d968df040caf0b9b86095e6f566289be7035c881cdbdb9ee369b525da2b3d",
+  "berimor-v0.29.0-linux-x64.tar.gz": "c5241ed293a81bf07ddeba06dbeaf8dd1ad3399768601dd4c675cbc8d81279b0",
+  "berimor-v0.29.0-win32-x64.zip": "df1cace7cf9d56dcc9141ca7c48cbde152aae8ac6186e53e6a73408e54f5490b"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "berimor",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Berimor — агентный CLI для LLM: интерактивный чат с инструментами (файлы, терминал, HTTP), детерминированные процессы, аудит и replay. Этот пакет — установщик платформенного бинарника.",
   "license": "Apache-2.0",
   "repository": {