Design notes ru

English · Русский

Заметки о решениях

Читайте это первым. Здесь записано, что решено, что открыто и с чего начать.

Что это за проект

agents-room — слой координации для ИИ-агентов, которые работают в разных репозиториях и должны договариваться друг с другом: API в одном репозитории, клиенты, которые его вызывают, — в других, каждый со своими сессиями и часто со своим харнессом. Он даёт комнаты репозиториев плюс общие комнаты, которые их связывают, присутствие сессий, лизы на файлы, обнаружение расхождений и адресацию по файлу или тегу — поверх MCP.

Случай одного репозитория — несколько сессий на одной кодовой базе — работает так же и является более простым, но он не является смыслом проекта. Он существует потому, что агенты в разных репозиториях иначе не видят друг друга вообще.

Автор идеи: Anton Sovetov. Лицензия: GPLv3, навсегда, не продаётся.

Порядок чтения

1. README.ru.md — проблема и форма ответа.
2. plan.md — рамки, архитектура, вехи, открытые вопросы.
3. protocol.md — модель данных, селекторы, состояния доставки, инструменты.
4. harness-setup.md — установка под каждый харнесс.
5. history/ — исходные русские черновики, только для истории.

Решено

Вопрос	Решение
Имя	agents-room
Лицензия	GPLv3, навсегда, не продаётся
Язык	Go, один статический бинарник, без cgo
Платформы	Linux, macOS, Windows на amd64 и arm64
Транспорт	нет: SQLite в режиме WAL, без демона
Интерфейс	MCP-сервер, без состояния, явная ручка сессии
Комнаты	repo:<имя> автоматически, плюс именованные общие комнаты
Доставка	однострочный нюдж, тело агент забирает сам
Автономия	три уровня, согласуются с оператором
Зависимости	ничего не скопировано из других проектов

Открыто

1. Живая проверка Codex. Адаптер следует контракту исходников Codex (Stop требует JSON-конверт, события инструментов тоже), но Codex на машине автора не установлен, поэтому сквозной прогон не делался.
2. Нужен ли hold свой предел на ход, ниже харнессного по умолчанию.
3. Автоматическая чистка. agents-room prune есть, но таймер его не запускает.
4. Отправка в комнату, где вы единственный участник, или в селектор file: на путь, который держите только вы, всё равно сохраняет сообщение с нулём получателей. Число сообщается обратно через msg_send и msg_recv, а не отправка отклоняется: широковещание в комнате из одного законно. Вернуться к этому, если агенты продолжат это упускать.
5. Комнаты, созданные до того, как join нормализовал префикс, остаются раздвоенными, потому что их слияние перенесло бы сессии между комнатами без их согласия. doctor называет каждое раздвоение и две команды, которые его чинят, а doctor --fix схлопывает случай дубликата чата, но намеренно не трогает раздвоенную комнату: перенос сессии между комнатами — решение самой сессии.
6. Сигнал пробуждения повторяется на событиях инструментов, но не на Stop. Повтор — то, что заставляет сообщение, предложенное однажды, снова объявить о себе; исключение Stop — то, что не даёт заблокированному ходу запустить следующий. Любое изменение wake.Check или retryWindow должно сохранять обе половины.
7. Сообщение принадлежит каждой комнате, в которой был отправитель, через message_rooms (версия схемы 6). Именно это делает историю общей комнаты полной. Это же значит, что одно сообщение может появиться в истории нескольких комнат — правильно, но стоит помнить при подсчёте трафика.
8. Повторный вход поднимает автономию сессии, но никогда не опускает, а doctor сообщает о каждой живой сессии ниже wake. Только wake может начать ход в простаивающем чате, поэтому чат ниже него недостижим и выглядит точно как сломанный хук. Раньше это случалось молча: room_join по MCP передавал autonomy обычным int с omitempty, вызов без поля приходил как 0, и повторный вход записывал его поверх уровня, поставленного хуком SessionStart. Две живые сессии стояли так на notify. Теперь поле на проводе — *int, а в хабе — JoinOptions.AutonomySet, поэтому «не указано» и «просили notify» — разные вещи; понижение — дело капа, и повторный вход, который его просит, получает об этом предупреждение.
9. Нюдж называет комнаты, через которые пришли его сообщения, а пустой msg_recv объясняет, почему он пуст. И то и другое — один и тот же дефект: ответ правильный, но неотличимый от другого, неверного. Нюдж раньше называл первую комнату сессии, а для межрепозиторного сообщения это почти никогда не та комната, куда оно пришло; msg_recv, вернувший пусто, раньше был одинаковым выводом и для догнавшей сессии, и для сессии в не той комнате. Названные комнаты пересекаются с членством читателя, а за пределами двух строка считает остальные.
10. id сессии, за которым ничего нет, — ошибка на каждом чтении, и ошибка называет id, который скорее всего имелся в виду. Неизвестный id и пустой ящик — оба ноль строк, поэтому без проверки неверный id невидим: один агент неделями передавал свой ключ харнесса в msg_recv и решил, что ему ничего не присылали, пока не накопилось девятнадцать сообщений. Ключ харнесса — обычная ошибка, потому что харнесс кладёт его в окружение, и он выглядит как идентичность; это ключ входа, а не id сессии. Инструменты, которые выводят комнату из сессии, отказывают вместо того, чтобы откатиться на текущий каталог, иначе опечатка в id пишет не в ту комнату.
11. Живость точна только на Linux — единственной поддерживаемой платформе с /proc. На Windows и macOS pid, время старта и окружение процесса недоступны без платформенного системного вызова, поэтому живость откатывается на «запущен ли pid», и строки-дубликаты нельзя привязать обратно к их чату. Откат слабее в одну сторону: перезапущенный MCP-сервер оставляет pid в строке устаревшим, и строка может читаться как gone, пока чат работает. Из этого ничего не угадывается — сессия без pid никогда не чистится, — и prune с room_who берут один и тот же откат, поэтому они согласованы друг с другом.

Правила для изменений

• Внутри репозитория — английский. Разговор с автором — русский.
• Никакого демона. Если изменению нужен демон, это неправильное изменение.
• Никакой зависимости, скопированной из другого проекта координации агентов.
• Каждое утверждение в документации должно быть верно для кода. Обновляйте документацию в том же коммите, что и код.
• Тесты не должны трогать ~/.agents-room; используйте AGENTS_ROOM_DB или временный путь.