steelmorgan/v8-session-manager

v8-session-manager

Тонкий MCP-агрегатор: принимает WS-подключения от 1С-клиентов и публикует их MCP-tools на едином HTTP-эндпоинте для AI-агента.

Что даёт сам менеджер

| Возможность | Источник | |---|---| | Встроенный tool — session_list (read-only снимок реестра) | менеджер | | Встроенный tool — tools_cache_reset (полный сброс или по config_id) | менеджер (ADR-0035) | | Витрина проксированных tools от подключённых клиентов | расширения 1С | | Persistent кеш витрины (workPath/tools_cache.json, TTL 5d) | менеджер (ADR-0035) | | Маршрутизация вызова в нужную сессию по session_id | менеджер | | Soft-reconnect клиента по client_uid | менеджер | | FIFO-порядок вызовов в одну сессию | менеджер |

Всё остальное (доменные tools — описание форм, запуск тестов, навигация и т.п.) добавляется расширениями 1С, не менеджером. Под каждое расширение — отдельный skill.

Кеш проксированных tools (ADR-0035) — ключевой момент

tools/list менеджера читается из persistent кеша на диске, а не только из живых WS-сессий. Следствия для агента:

• Имя tool в tools/list ≠ доступность вызова. Кеш переживает disconnect клиента и рестарт менеджера — имя остаётся на витрине, но вызов без live-сессии вернёт MCP tool error isError:true, _meta.error_code="no_live_session". Это не баг, это контракт.
• Зачем так: часть MCP-харнесов (в частности Claude Code) нестабильно реагирует на notifications/tools/list_changed. Persistent-кеш снимает зависимость от стабильной обработки нотификации.
• Когда нужен tools_cache_reset: когда tool осознанно удалён из расширения и больше не вернётся (или конфигурация снята полностью). Иначе он будет висеть до истечения TTL (по дефолту 5 суток с момента последнего session.register). Полный сброс — без аргументов; точечный — {"config_id": "<id>"} (берётся из session_list[*].config_id).
• Что НЕ делает кеш: не запускает 1С, не воспроизводит ответ tool, не подменяет live-сессию. Только хранит имена и inputSchema.

Подробности — references/sessions-and-tools.md § «Persistent кеш и tools_cache_reset».

Границы

Менеджер не:

• запускает 1С-клиентов (это работа внешнего оркестратора, типично — v8-runner);
• хранит состояние между перезапусками (реестр in-memory);
• содержит бизнес-логику (только транспорт + маршрутизация);
• управляет ИБ.

Routing задач

| Задача | Reference | |---|---| | Что делает каждый слой стека (addin → devkit → BSL → менеджер → AI) | references/architecture.md | | Поднять менеджер, подключить 1С-клиента | references/bootstrap.md | | Прочитать session_list, вызвать tool, понять почему он отсутствует | references/sessions-and-tools.md | | Добавить новый tool в расширение 1С | references/extending-tools.md | | Менеджер не стартует / клиент не виден / tool скрыт / вызов падает | references/troubleshooting.md |

Guardrails (hard)

1. Не править исходники менеджера (src/, Cargo.toml, systemd/, etc/, spec/, ADR в docs/decisions/) — это upstream-репозиторий. Все изменения уровня менеджера согласуются отдельной задачей.
2. Не создавать и не менять MCP-tools без прямого разрешения пользователя. Tools живут в расширениях 1С (exts/<extension>/); правка/добавление = изменение публичного контракта.
3. Не тащить бизнес-логику в менеджер. Если задача требует «менеджер должен делать X» — это сигнал, что X относится либо к расширению, либо к оркестратору запуска.
4. Не пытаться запустить 1С-клиента через менеджер. Менеджер только принимает входящее WS-подключение. Запуск 1С — задача v8-runner.
5. Перед сборкой/перезапуском клиента — спросить пользователя. Любая операция, меняющая состояние проекта (билд, рестарт), требует подтверждения.