Три CLI‑агента, один Telegram‑интерфейс: JSON‑RPC, ACP, worktree и контроль разрешений

Codex CLI, Claude Code и Cursor Agent могут работать без участия человека: читать код, редактировать его, запускать тесты, а затем остановиться на запросе разрешения. Это удобно, пока терминал перед глазами. Если отойти от компьютера, остаются два неплохих, но не всегда удобных варианта: подключаться по SSH с телефона или узнавать о запросе агента уже после возвращения. Также можно включить автономный режим без подтверждения, но это не подходит для ситуаций, когда нужно назначить задачи, находясь далеко от ПК.

Чтобы держать агентов под контролем, даже находясь в дали от терминала, я решил сделать продукт AI Control — локальный Telegram‑пульт для этих трёх CLI. Процесс работает на том же компьютере, что и проекты, сам получает обновления Telegram через long polling и не открывает входящий порт. Дополнительного сервера AI Control нет: исходники, рабочие каталоги, база и сессии хранятся локально. При этом текст сообщений и явно отправленные файлы проходят через инфраструктуру Telegram; сквозного шифрования у ботов нет.

https://github.com/Mi‑Mih/ai_control — это рабочий MVP для одного пользователя и собственных репозиториев — не удалённый shell и не универсальная песочница.

В чате выбираю проект, агента, модель и место запуска: текущий checkout или отдельный Git worktree. Затем отправляю задачу. Бот редактирует одну карточку, показывая текущий этап, время последней активности и длительность этапа. Когда ход заканчивается, в карточке остаётся короткий итог, а полный ответ можно получить отдельным сообщением или файлом.

Следующее сообщение продолжает ту же сессию. Можно также подключить сохранённую сессию, ранее начатую в терминале, но нельзя перехватить уже работающий чужой процесс. Для одной задачи доступны статус, краткий git diff, изменённые файлы, смена модели и режимов перед следующим запуском.

Самая сложная часть: три разных протокола

Снаружи агенты похожи, но унифицировать их на уровне запуска процесса недостаточно.

Codex работает через codex app-server по JSON‑RPC. После initialize адаптер вызывает thread/start или thread/resume, затем turn/start; остановка идёт через turn/interrupt. Текущий этап получается из структурированных событий item/started и item/completed, а итог — из сообщения с фазой final_answer.

Claude Code использует двусторонний поток JSON Lines с --input-format=stream-json и --output-format=stream-json. В этот же поток приходят запросы разрешений и ответы на них. Интерактивный TUI в качестве запасного канала не используется: если установленная версия CLI не поддерживает нужный режим, это показывает doctor.

Cursor Agent говорит по ACP поверх JSON‑RPC на stdio. Его сессия тоже сохраняется и может быть продолжена следующим сообщением.

Я также отказался от «процента готовности». Ни один из протоколов не сообщает достоверную долю выполненной работы. Этап «запускает тесты» и таймер честнее псевдоточного прогресс‑бара.

Два независимых переключателя безопасности

Файловый доступ и способ подтверждения — разные свойства задачи. Автоподтверждение не должно случайно расширять область записи.

У проекта в локальном config.yaml задан начальный режим и одновременно верхняя граница для новых задач:

• read_only — без записи;

• project_only — запись внутри корня проекта после разрешения символических ссылок;

• approved_paths — проект плюс явно перечисленные каталоги;

• full_access — права обычного пользователя ОС, запустившего бот.

full_access можно задать только локально. Telegram‑кнопка его не включает. Если полнодоступную задачу понизить, вернуть ей полный доступ из чата или перезапуском нельзя — нужно создавать новую задачу. Режим хранится в SQLite отдельно для каждой задачи.

В ручном режиме запрос разрешения привязан к пользователю, задаче и идентификатору действия. Ответ удаляется из памяти адаптера до отправки в CLI, поэтому повторное нажатие callback ничего не разрешит. Общей кнопки «разрешить всё» нет.

В автоматическом режиме Codex и Cursor получают соответствующие параметры CLI, а адаптеры дополнительно обрабатывают структурированные запросы разрешений. Для Claude решение принимает адаптер после проверки собственной политики. Во всех случаях запрос на выход за файловую границу отклоняется и записывается в аудит.

Эта схема ограничивает изменения, но не обещает строгую изоляцию чтения. Например, процесс Codex может прочитать доступный пользователю файл вне проекта, даже если не способен его изменить. Для настоящей границы чтения нужна отдельная учётная запись ОС, контейнер или виртуальная машина. Песочница CLI — дополнительный барьер, а не замена изоляции ОС.

Worktree, сбои и остановка процессов

Worktree создаются автоматически, но не удаляются при закрытии задачи. Автоочистка могла бы уничтожить незакоммиченные изменения, поэтому ветку нужно проверить, объединить или удалить обычными средствами Git.

Дочерний процесс запускается массивом аргументов без оболочки. В Unix он получает новую сессию и завершается всей группой. В Windows создаётся новая группа процессов, которая завершается через taskkill /T. Для WSL тот же массив оборачивается в wsl.exe с явно заданными дистрибутивом и Linux‑каталогом.

Второй экземпляр AI Control с тем же каталогом данных не стартует: иначе процессы конкурировали бы за один long polling и одну базу. Команда /panic STOP прекращает приём задач, останавливает активные процессы и штатно завершает polling. Пользовательский юнит systemd использует Restart=on-failure, поэтому после такой остановки сам не поднимается.

Безопасность

Токен бота берётся из переменной окружения, системного хранилища учётных данных или закрытого secrets.json в каталоге данных; в SQLite и пример конфигурации он не попадает. Журналы ротируются и маскируют типичные токены, пароли, заголовки авторизации и PEM‑ключи.

Модель доверия всё равно остаётся простой: авторизованный Telegram‑аккаунт может поручать агенту менять зарегистрированные проекты в разрешённом режиме. Пароли, ключи и профили браузера отправлять боту не стоит:)

Ограничения проекта

• У Telegram‑ботов нет сквозного шифрования.

• Потерянная после сбоя задача не подключается к старому дочернему процессу; продолжение запускает новый процесс по сохранённому ID сессии.

• Подключение внешней сессии переносит её историю, но не управление уже работающим CLI.

• Вложения во время активного хода сами не добавляются в промпт.

• На Windows taskkill /T надёжен для обычных потомков, но не догоняет процесс, который вышел из группы. Job Object оставлен на будущее.

• Лимиты подписки Claude Code и Cursor из этих протоколов не видны. Для Codex /usage получает лимиты через app-server; для Claude бот показывает накопленные по задаче токены и стоимость.

• Проекты, модели и верхние границы доступа меняются только локально в конфигурации с последующим перезапуском.

Но для моего сценария — собственные репозитории на личном компьютере — оказалось достаточно: задачи продолжаются с телефона, параллельные изменения расходятся по worktree, а запросы разрешений не требуют держать терминал открытым перед глазами.

Исходный код и инструкция: https://github.com/Mi‑Mih/ai_control.