From 144f6a5d59d5898403512f80c6f9d5f706bc5d6b Mon Sep 17 00:00:00 2001 From: Hermes Team Date: Wed, 2 Sep 2026 23:29:33 +0700 Subject: [PATCH] =?UTF-8?q?docs(research):=20=D1=80=D0=B5=D1=88=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D0=B8=20=D0=BF=D0=BB=D0=B0=D0=BD=20=D1=81?= =?UTF-8?q?=D0=BB=D0=B8=D1=8F=D0=BD=D0=B8=D1=8F=20Hermes=20Hub=20=E2=86=92?= =?UTF-8?q?=20KAgent?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Владелец принял направление: один продукт KAgent, функциональность Hermes переносится нативно, после parity Hermes архивируется. На переходный период KAgent доделывается на одном сервере, Hermes — на втором. Ревьюер проверил обе стороны исполнением, а не по аудиту: - Hermes: CI на main красный; баг pricing fallback реален (safe_dump вместо safe_load в telemetry_service.py:164, таблица цен не грузится). - KAgent (head 131c9b08): лицензии нет; в reasoning-engine/src/server.py require_operator_secret стоит на управлении аккаунтами, но НЕ на /v1/execute, /v1/decide, /v1/telemetry — расход провайдера открыт без авторизации. Поправка к аудиту: последняя активность 18-19 августа, репозиторий замер. Жёсткий гейт: ключи провайдеров не переезжают в KAgent, пока эти маршруты не закрыты и это не проверено живым запросом. Сам план миграции положен в репозиторий как артефакт, чтобы не жил только файлом на столе. Co-Authored-By: Claude Opus 5 --- docs/research/README.md | 4 + docs/research/kagent-merge-decision.md | 113 +++++++++++++++++++++++++ docs/research/kagent-merge-plan.md | 107 +++++++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 docs/research/kagent-merge-decision.md create mode 100644 docs/research/kagent-merge-plan.md diff --git a/docs/research/README.md b/docs/research/README.md index 45b98a9..763e564 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -16,3 +16,7 @@ ближайшего архитектурного родственника Hub; что перенять, чего не брать. - [scouting-log.md](scouting-log.md) — журнал разведки: что рассмотрено по датам, с вердиктом по каждому пункту и причиной. +- [kagent-merge-decision.md](kagent-merge-decision.md) — решение о слиянии с + KAgent: проверенные ревьюером находки, жёсткий гейт на перенос ключей, порядок. +- [kagent-merge-plan.md](kagent-merge-plan.md) — сам план миграции Hermes → KAgent + по фазам, положен в репозиторий как артефакт. diff --git a/docs/research/kagent-merge-decision.md b/docs/research/kagent-merge-decision.md new file mode 100644 index 0000000..6c076e1 --- /dev/null +++ b/docs/research/kagent-merge-decision.md @@ -0,0 +1,113 @@ +# Решение: слияние Hermes Hub и KAgent + +**Дата:** 2026-09-02. +**Статус:** направление принято владельцем; исполнение — по условиям ниже. +**Ревьюер проверил исполнением** обе стороны, насколько имел доступ. + +--- + +## Решение + +Вести один продукт — **KAgent** как единую AI-платформу. Функциональность +Hermes Hub переносится в KAgent нативно, Hermes Hub после достижения parity +архивируется. Полный план — [kagent-merge-plan.md](kagent-merge-plan.md). + +Организация работы на переходный период (решение владельца от 2026-09-02): + +- **KAgent** дорабатывается на одном сервере; +- **Hermes Hub** доводится на втором сервере; +- после доработки — слияние; +- **KAgent готовится к слиянию сразу**, с первого дня: контракты и модель + безопасности проектируются под будущий перенос, а не подгоняются потом. + +--- + +## Что ревьюер проверил сам, а не взял из аудита + +Аудиты — тоже отчёты, поэтому проверены исполнением. Спот-проверка совпала с +аудитами на конкретных утверждениях — значит доверять им можно, но с поправками +ниже. + +### Hermes Hub + +- **CI на `main` красный** — подтверждено, несколько падений 2026-09-02. +- **Баг pricing fallback реален**: `telemetry_service.py:164` делает + `yaml.safe_dump(p.read_text(...))` вместо `safe_load`, затем проверяет + `isinstance(data, dict)` — всегда ложно, и `except: pass` это глушит. Таблица + цен из `pricing.yaml` не загружается никогда. Аудит: P2. Подтверждено. + +### KAgent (репозиторий `ochenstarik-ui/kagent`, head `131c9b08`) + +- **Лицензии нет**, репозиторий публичный — подтверждено. +- **Публичный расход средств подтверждён чтением `services/reasoning-engine/src/server.py`:** + функция `require_operator_secret` существует и применяется к управлению + аккаунтами (`/v1/accounts`, `pin`, `disable`, `reset-throttle`), но **НЕ** + применяется к `/v1/execute`, `/v1/decide`, `/v1/telemetry`, `/v1/models`. + `/v1/execute` вызывает `engine.execute(...)` — реальный расход. То есть с + подключёнными ключами любой, кто найдёт порт, тратит квоты без авторизации. + Это не гипотеза, а код на `main`. +- **Поправка к аудиту:** аудит датирован 2026-09-02 и говорит об «активности + после релиза», но последний push в KAgent — **18–19 августа**, две недели + тишины. CI зелёный, но старый. KAgent сейчас не разрабатывается активно. На + выводы о коде это не влияет (head-коммит совпал), на планирование сроков — + влияет. + +--- + +## Жёсткий гейт (не обсуждается) + +**Ни один ключ провайдера не переезжает в KAgent, пока `/v1/execute`, +`/v1/decide` и `/v1/telemetry` не закрыты авторизацией и это не проверено живым +запросом.** У владельца ~2 десятка оплаченных аккаунтов. Пока маршруты открыты, +KAgent небезопасен даже без слияния — это надо чинить в нём независимо. + +Это соответствует Phase 0 плана слияния и P0 аудита KAgent. + +--- + +## Порядок, который советует ревьюер + +Направление верное — два оркестратора не нужны, Крона не должна знать о Hermes. +Но последовательность важнее скорости: + +1. **Hermes довести до зелёного и стабильного** прежде, чем замораживать. Он — + эталон переноса (reference implementation). Сломанный эталон нельзя + портировать: parity-тесты будут сверяться с неверным поведением. Сегодня + Hermes ещё нестабилен — аккаунты едва работают, `agy`-патч слетает после + перезагрузки, `main` красный. +2. **KAgent Phase 0 (безопасность) — закрыть и проверить исполнением**, начиная + ровно с четырёх незакрытых маршрутов. До этого — никаких ключей. +3. **Контракт выполнения (Phase 1)** можно проектировать уже сейчас, риска нет: + `AIExecutionRequest`, `AIExecutionResult`, `ProviderAdapter`, таксономия + ошибок, `RoutingDecision`. + +## Почему «rewrite не нужен» — неточность + +Скелет KAgent есть, но роутер Hermes не портируется построчно: он переезжает в +другую архитектуру (Rust gateway, TS control plane, Python-сервисы, +распределённое состояние Redis/Postgres/NATS вместо процесса). Это честный +rewrite роутера. Сроки планировать от этого. + +## Что перенести из Hermes (проверенные тонкости, легко потерять при переносе) + +Эти вещи вскрылись только живым прогоном и обязаны попасть в parity-набор: + +- вход `agy` читается из `.gemini/antigravity-cli/antigravity-oauth-token`, не из + формата Gemini CLI; +- терминалу входа нельзя подменять `HOME` (X11 берёт ключ из `~/.Xauthority`); +- `/props` и `/tokenize` у llama.cpp — в корне, не под `/v1`; +- слот выбирается до входа и не должен плодиться; запрос пути профиля не должен + создавать каталог; +- проверка после подключения не блокирует ответ; +- честное `Н/Д` с причиной вместо правдоподобных чисел. + +Подробности — в [../../agents/](../../agents/) и передаточном брифе. + +--- + +## Координация + +Две сессии Claude пишут в один `main` Hermes Hub (сессия на ПК — ревьюер; сессия +на сервере под `ochenstarik` — исполнитель). Плюс крупный разворот стратегии. +Обе сессии должны видеть это решение. Перед пушем — `git fetch` и сверка +`git log --oneline origin/main`. diff --git a/docs/research/kagent-merge-plan.md b/docs/research/kagent-merge-plan.md new file mode 100644 index 0000000..171e317 --- /dev/null +++ b/docs/research/kagent-merge-plan.md @@ -0,0 +1,107 @@ +# План слияния Hermes Hub → KAgent + +Источник — план владельца от 2026-09-02, положен в репозиторий, чтобы не жил +только файлом на рабочем столе. Оценка и условия исполнения — в +[kagent-merge-decision.md](kagent-merge-decision.md). + +## Цель + +KAgent становится единой AI Agent Operating Platform. Функциональность Hermes Hub +переносится нативно, Hermes Hub и Hermes Agent перестают быть зависимостями, +Hermes Hub архивируется. Hermes Hub на переходный период — донор функциональности +и эталон поведения, не встраиваемая библиотека. + +## Разделение обязанностей + +- **Orchestrator** выбирает агента, workflow, инструменты, контекст, проверку, + момент завершения. +- **AI Router** выбирает провайдера, модель, аккаунт, локально/облако, failover, + проверяет квоту, доступность, бюджет, вычислительный узел. + +> Orchestrator выбирает агента и задачу. Router выбирает модель, провайдера и +> аккаунт. + +## Что переносится из Hermes + +Multi-provider router; адаптеры провайдеров (Antigravity, Claude, Codex, +DeepSeek, Grok, Local, NVIDIA, Ollama, OpenCode, OpenRouter); менеджер +аккаунтов/профилей (несколько аккаунтов на провайдера, приоритет, quota, +cooldown, health, concurrency); health-состояния; quota manager; session +affinity; lease/concurrency; model registry; capability-routing; локальные +модели и вычислительные узлы; agent registry (15 ролей как декларативные +Agent Definition); Dual Coder как workflow; Guardian как policy-слой; Cost +Controller как системная подсистема; failover-policy с таксономией ошибок; +telemetry в существующий Observability; audit routing-решений. + +## Что НЕ переносить + +Hermes-specific bootstrap; дублирующий Web API и отдельный UI; process-local +архитектуру; JSONL как основное хранилище telemetry; формат настроек Hermes; +update flow Hermes; роль orchestrator как отдельный runtime; код, привязанный к +структуре Hermes Agent; compatibility-слои, не нужные после миграции. + +Секреты: не переносить хранилище Hermes один-в-один. Порядок — внешний Secret +Manager → OS/keyring → шифрованное хранение в БД → материализация только на время +запроса. Запрещено: ключи в обычных JSON, отдача секретов через API, секреты в +telemetry/audit/трейсах. + +## Фазы + +- **Phase 0 — Security baseline (блокер).** Auth/RBAC; защита расхода провайдера; + service-auth; безопасное хранение секретов; уникальная request identity; + реальный E2E. Выход: нет неавторизованного execution и мутаций проекта/задачи; + расход защищён; CI зелёный; E2E по настоящему пути зелёный. +- **Phase 1 — контракты Router.** AIExecutionRequest, AIExecutionResult, + ProviderAdapter, Model/Account descriptor, таксономия ошибок, RoutingDecision. + Провайдеры пока не переносить. Выход: contract-тесты, fake-адаптер, роутер на + тестовых провайдерах. +- **Phase 2 — Provider SDK.** timeout, cancellation, streaming, маппинг ошибок, + usage, cost, health, discovery. Выход: новый провайдер добавляется без правки + ядра. +- **Phase 3 — перенос адаптеров.** Порядок: openai-compatible → Claude → + OpenRouter → Google/Antigravity → Grok → DeepSeek → NVIDIA → Ollama → Codex → + OpenCode → local. Для каждого: parity, таксономия ошибок, health/auth/ + streaming/timeout/quota/regression тесты. +- **Phase 4 — Account Manager.** Безопасные credentials, приоритет, quota, + cooldown, health, concurrency, переходы состояний. +- **Phase 5 — Router Engine.** role/capability routing, scoring, preferred chain, + health/quota awareness, same-account и cross-account/provider fallback, session + affinity, auto-return primary, failover trace. +- **Phase 6 — распределённое состояние.** Redis (health, leases, affinity, + cooldown), PostgreSQL (providers, accounts, models, policies, budgets, usage, + nodes, agents). +- **Phase 7 — локальные модели / compute nodes.** node agent: регистрация, + heartbeat, инвентарь моделей и ресурсов, execution, queue, GPU. +- **Phase 8 — Agent Registry.** декларативные определения: capabilities, tools, + permissions, routing policy, budgets, model constraints. +- **Phase 9 — Guardian** как policy enforcement: валидация команд, границы ФС, + сигналы prompt injection, детект секретов, проверка прав инструментов, сетевая + политика, классификация разрушительных действий. +- **Phase 10 — Cost Controller.** оценочная и фактическая стоимость, жёсткие + бюджеты, наследование, cloud/local оптимизация, alerts, kill switch. +- **Phase 11 — Workflows.** Dual Coder как workflow; шаблоны Coder+Reviewer, + Coder+Tester, Security Review, Multi-model Consensus, Local Draft + Cloud + Review. +- **Phase 12 — UI.** разделы Providers, Accounts, Models, Routing, Nodes, Quotas, + Budgets, Usage, Health, Agents. +- **Phase 13 — parity-тесты.** Чек-лист до отключения Hermes: все провайдеры, + несколько аккаунтов, quota exhaustion, rate limit, auth failure, failover, + локальные модели, session affinity, выбор модели, health, telemetry, Dual + Coder, роли. +- **Phase 14 — decommission Hermes.** запрет новых фич → deprecated → KAgent + единственный production path → удаление зависимостей → финальный релиз Hermes → + archived. + +## Критерий отказа от Hermes + +Архивировать только когда KAgent умеет: все нужные облачные провайдеры; +несколько аккаунтов; локальный AI; авто-выбор модели; failover; учёт quota; +health; session affinity; telemetry; расчёт cost; роли агентов; эквивалент Dual +Coder; проверки Guardian; бюджеты; работу на Windows/Linux; полный parity-набор. + +## Обязательные P0 KAgent до миграции (из его аудита, часть проверена ревьюером) + +Control Plane auth/RBAC (не доверять `x-actor-id`); авторизация +`/v1/execute` и `/v1/decide` (**подтверждено: сейчас открыты**); уникальная +request identity; фикс double-consume TOTP; настоящий E2E через Gateway, не mock; +добавить LICENSE (**подтверждено: отсутствует**).