ACP Внутреннее устройство

Адаптер ACP оборачивает синхронный AIAgent Hermes в асинхронный stdio-сервер JSON-RPC.

Ключевые файлы реализации:

acp_adapter/entry.py
acp_adapter/server.py
acp_adapter/session.py
acp_adapter/events.py
acp_adapter/permissions.py
acp_adapter/tools.py
acp_adapter/auth.py
acp_registry/agent.json

Процесс запуска

hermes acp / hermes-acp / python -m acp_adapter
  -> acp_adapter.entry.main()
  -> load ~/.hermes/.env
  -> configure stderr logging
  -> construct HermesACPAgent
  -> acp.run_agent(agent, use_unstable_protocol=True)

Stdout зарезервирован для ACP JSON-RPC транспорта. Человекочитаемые логи направляются в stderr.

Основные компоненты

`HermesACPAgent`

acp_adapter/server.py реализует протокол агента ACP.

Обязанности:

инициализация / аутентификация
методы сессий new/load/resume/fork/list/cancel
выполнение prompt
переключение модели сессии
подключение обратных вызовов AIAgent к асинхронным уведомлениям ACP

`SessionManager`

acp_adapter/session.py отслеживает активные сессии ACP.

Каждая сессия хранит:

session_id
agent
cwd
model
history
cancel_event

Менеджер потокобезопасен и поддерживает:

create
get
remove
fork
list
cleanup
cwd updates

Мост событий

acp_adapter/events.py преобразует колбэки AIAgent в события ACP session_update.

Передаваемые через мост колбэки:

tool_progress_callback
thinking_callback
step_callback
message_callback

Поскольку AIAgent выполняется в рабочем потоке, а ACP I/O работает в основном цикле событий, мост использует:

asyncio.run_coroutine_threadsafe(...)

Мост разрешений

acp_adapter/permissions.py преобразует опасные запросы подтверждения в терминале в запросы разрешений ACP.

Сопоставление:

allow_once -> Hermes once
allow_always -> Hermes always
опции отклонения -> Hermes deny

Тайм-ауты и сбои моста по умолчанию запрещают действие.

Вспомогательные средства рендеринга инструментов

acp_adapter/tools.py сопоставляет инструменты Hermes с типами инструментов ACP и формирует содержимое для редактора.

Примеры:

patch / write_file -> различия файлов
terminal -> текст команд оболочки
read_file / search_files -> предварительный просмотр текста
большие результаты -> усечённые текстовые блоки для безопасности интерфейса

Жизненный цикл сессии

text
new_session(cwd)
  -> создать SessionState
  -> создать AIAgent(platform="acp", enabled_toolsets=["hermes-acp"])
  -> привязать task_id/session_id к переопределению cwd
```prompt(..., session_id)
  -> извлечение текста из блоков контента ACP
  -> сброс события отмены
  -> установка callback-функций + моста одобрения
  -> запуск AIAgent в ThreadPoolExecutor
  -> обновление истории сессии
  -> отправка финального фрагмента сообщения агента

Отмена

cancel(session_id):

устанавливает событие отмены сессии
вызывает agent.interrupt() при наличии
приводит к тому, что ответ prompt возвращает stop_reason="cancelled"

Форкинг`fork_session()` выполняет глубокое копирование истории сообщений в новую активную сессию, сохраняя состояние разговора и при этом предоставляя форку собственный идентификатор сессии и рабочий каталог.

Поведение Provider/auth

ACP не реализует собственное хранилище аутентификации.

Вместо этого он повторно использует резолвер среды выполнения Hermes:

acp_adapter/auth.py
hermes_cli/runtime_provider.py

Таким образом, ACP объявляет и использует текущий настроенный provider/credentials Hermes.

Привязка рабочего каталогаACP сессии несут с собой рабочий каталог редактора.

Менеджер сессий привязывает этот рабочий каталог к идентификатору сессии ACP через переопределения terminal/file с областью видимости задачи, поэтому инструменты для работы с файлами и терминалом работают относительно рабочего пространства редактора.

Дублирующиеся вызовы инструментов с одинаковым именем

Мост событий отслеживает идентификаторы инструментов FIFO для каждого имени инструмента, а не только один идентификатор на имя. Это важно для:

параллельных вызовов с одинаковым именем
повторяющихся вызовов с одинаковым именем на одном шагеБез очередей FIFO события завершения привязывались бы к неверному вызову инструмента.

Восстановление callback-функции одобрения

ACP временно устанавливает callback-функцию одобрения на инструмент терминала во время выполнения prompt, а затем восстанавливает предыдущую callback-функцию. Это позволяет избежать того, чтобы обработчики одобрения, специфичные для сессии ACP, оставались установленными глобально навсегда.

Текущие ограничения

ACP сессии сохраняются в общей ~/.hermes/state.db (SessionDB) и прозрачно восстанавливаются при перезапуске процессов; они отображаются в session_search
нетекстовые блоки prompt в настоящее время игнорируются при извлечении текста запроса
UX редактора варьируется в зависимости от реализации клиента ACP

Связанные файлы

tests/acp/ — набор тестов ACP
toolsets.py — определение набора инструментов hermes-acp
hermes_cli/main.py — подкоманда hermes acp CLI
pyproject.toml — необязательная зависимость [acp] + скрипт hermes-acp