Codex Hermes A2A Bridge

Локальный мост, который делает Codex «точкой входа»: Codex вызывает MCP-инструменты через stdio, а bridge преобразует запросы в A2A v1.0/JSON-RPC к профилю Hermes default, после чего сохраняет сопоставления диалогов/задач в SQLite. Hermes по-прежнему остаётся «мозгом», выполняющим agent loop, memory, skills, tools и внутреннюю оркестрацию.

Текущая версия: v0.1.1. Доступен только bind/call для loopback-эндпоинта; нет инструментов для смены модели, плагинов, конфигурации, обновлений, shell или управления сервисом Hermes.

Независимый проект: это независимое программное обеспечение сообщества, не являющееся официальным продуктом, не имеющее спонсорской поддержки и не представляющее Nous Research/Hermes Agent или OpenAI/Codex. Торговые марки используются только для описания совместимости.

Архитектура

Codex client --MCP stdio--> MCP server --> bridge core --> Hermes A2A :9900
                                      \--> SQLite context/task mapping

• Python 3.11 и отдельное виртуальное окружение, не используется venv Hermes.

• Официальный MCP SDK для Python, асинхронный httpx, Pydantic и стандартная библиотека SQLite.

• Каждый новый conversation_key сопоставляется с contextId Hermes; последующие витки используют это сопоставление.

• Исходные промпты не сохраняются; мост хранит fingerprint, маршрут, состояние, результаты и минимизированные ошибки.

Related MCP server: ccg-mcp

Требования и быстрая установка

• Python 3.11.

• Hermes Agent 0.20.5 с включённым A2A gateway на loopback.

• Codex-клиент с поддержкой MCP stdio.

cd /absolute/path/to/codex-hermes-a2a-bridge
python3.11 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/codex-hermes-a2a-bridge doctor

Контрибьютор может установить дополнительные средства тестирования командой python -m pip install -e '.[dev]'. Переопределения описаны в .env.example; не коммитьте настоящий файл .env.

Безопасная конфигурация по умолчанию:

Включение Hermes A2A и регистрация Codex

На уже установленной локально Hermes 0.20.5:

hermes plugins enable a2a-platform --no-allow-tool-override
hermes config set gateway.platforms.a2a.enabled true
hermes gateway run --no-supervise

При работе через foreground pass можно установить пользовательский сервис (без sudo):

hermes gateway install --start-now --start-on-login

Зарегистрируйте мост в общей конфигурации Codex:

codex mcp add codex-hermes-a2a-bridge -- \
  /absolute/path/to/codex-hermes-a2a-bridge/.venv/bin/codex-hermes-a2a-bridge serve
codex mcp get codex-hermes-a2a-bridge

Чтобы новая запись была прочитана, необходимо открыть или перезапустить клиент Style. MCP stdio записывает в stdout только протокольные фреймы; диагностика выводится в stderr.

Семь MCP-инструментов v0.1

Набор четырёх MVP-операций, упомянутых в исследовании (discover, send, get, continue), — не полный A2A. V0.1 объединяет их в семь высокоуровневых инструментов для работы с диалогами и задачами; более низкоуровневые операции A2A, такие как CRUD для push-уведомлений и администрирование Hermes, напрямую не экспонируются.

Пример рабочего процесса

1. Codex вызывает hermes_status.

2. Codex вызывает hermes_chat(message=..., rescue_key=<стабильный>, mode="auto").

3. Если задача всё ещё выполняется, используйте hermes_task_wait или hermes_task_get; не отправляйте вслепую после неоднозначного таймаута.

4. Если needs_input=true, спросите пользователя и затем вызовите hermes_chat с тем же conversation_key/context_id.

5. Следующий виток диалога продолжает то же сопоставление; hermes_contexts(action="close") закрывает только сопоставление в bridge.

Для операций с побочными эффектами указывайте idempotency_key. Hermes 0.20.5 не поддерживает идемпотентность на сетевом уровне, поэтому мост не отправляет повторно мутирующий send, если результат передачи неясен.

Начиная с v0.1.1, все три режима используют SendStreamingMessage, чтобы получать A2A-идентификаторы задач уже в первом событии. sync ждёт inline не более 30 секунд (или меньше, если задан меньший timeout); поток продолжает жить до correlation timeout. Для старых записей в состоянии outcome_unknown, не содержащих A2A ID, hermes_task_get/hermes_task_wait сначала пробуют ListTasks(contextId), затем читают официальное conversation persistence из Hermes. Восстановление присваивает результат только в том случае, когда есть ровно одна локальная нерешённая задача и ровно один remote/disk-кандидат; неоднозначные случаи оставляются без изменений: без повторной отправки и без догадок. Disk fallback не имеет состояния A2A, поэтому возвращает предупреждение и считает сохранённый ответ Hermes завершённым (completed).

Тестирование и эксплуатация

.venv/bin/pytest --cov=codex_hermes_a2a_bridge --cov-report=term-missing
.venv/bin/codex-hermes-a2a-bridge doctor
.venv/bin/codex-hermes-a2a-bridge smoke \
  'Reply with exactly MY_MARKER and nothing else.' \
  --conversation-key manual-smoke
.venv/bin/python scripts/live_check.py manual-smoke

pytest использует фейковый A2A-сервер на случайном loopback-порту и не требует реальной Hermes. doctor и live_check.py доступны только для чтения. Команда smoke отправляет реальный запрос; запускайте её с безобидным содержимым и только осознанно.

Безопасность и конфиденциальность

• V0.1.1 отклоняет эндпоинты и Agent Card URL не из loopback, не переходит по редиректам и не принимает токен через MCP-аргументы.

• SQLite по умолчанию находится за пределами исходного кода и имеет права 0600; в нём хранятся сопоставления, fingerprint, состояния, результаты и артефакты, а также минимальные ошибки. Результаты могут содержать конфиденциальные данные, поэтому применяйте соответствующие политики хранения и резервного копирования.

• Исходные промпты мостом не сохраняются, однако Hermes может вести собственные журналы диалогов/аудита. Fallback-восстановление читает только настроенную директорию диалогов Hermes.

• MCP-сервер должен запускать доверенный пользователь; семь инструментов могут активировать Hermes, использующий навыки и инструменты с побочными эффектами. Используйте idempotency_key и не делайте слепых повторов при outcome_unknown.

• Сообщайте об уязвимостях согласно SECURITY.md. Не публикуйте токены, транскрипты или SQLite в issue.

Гарантии и ограничения апстрима

Мост обеспечивает политику loopback, надёжное локальное сопоставление, отсутствие повторных мутирующих send-запросов при неопределённости и честную семантику отмены. Мост не гарантирует, что Hermes остановила вычисления, потоковую передачу на уровне токенов, идемпотентность на уровне протокола или сохранность задач при перезапуске Hermes.

Hermes 0.20.5 использует in-memory TaskStore, SSE-жизленный цикл, а отмена по протоколу не прерывает активный виток. Fallback-восстановление на основе conversation-store со стороны моста является условным и читающим; он не заменяет durable TaskStore ат повышable обновление. Проверенные подробности перечислены в Hermes A2A reference.

Troubleshooting

• a2a_unreachable: запустите hermes gateway status и проверьте карточку http://127.0.0.1:9900/.well-known/agent-card.json.

• Плагин A2A отмечен как включённый, но порт не запускается: проверьте hermes config get gateway.platforms.a2a.enabled, затем перезапустите gateway.

• Codex не видит инструменты: выполните codex mcp get codex-hermes-a2a-bridge, затем используйте новый процесс/клиент Codex.

• outcome_unknown: вызовите hermes_task_get/hermes_task_wait, чтобы мост выполнил восстановление; если ситуация остаётся неоднозначной, не отправляйте задачу с сайд-эффектами повторно и уточните у пользователя.

• turn_budget_exceeded: закройте сопоставление и создайте новый диалог; не увеличивайте лимит просто для того, чтобы агент мог повторяться бесконечно.

• Hermes 0.20.5 теряет in-memory TaskStore при перезапуске; мост сохраняет локальную задачу/результат, но удалённый refresh может сообщить, что задача больше не существует.

• macOS: если launchctl bootstrap возвращает exit 5, Hermes запускается через detached fallback: она работает, но не стартует и не перезапускается автоматически. Для подтверждения используйте hermes gateway status.

Откат

См. scripts/rollback.sh. По умолчанию скрипт только выводит план. scripts/rollback.sh --apply удаляет именно zip MCP entry и A2A-конфигурацию/плагин, но сохраняет gateway-сервис, потому что он может обслуживать другие платформы. Добавляйте --include-gateway-service только если gateway был установлен исключительно для этого rollout. Исходные коды, .venv, SQLite и транскрипты Hermes сохраняются как есть.

Бэкапы, ограниченные сферой действия, создаются рядом с файлами конфигурации с суффиксом .pre-codex-hermes-a2a-bridge-v0.1.bak; автоответcтвие автоматического восстановления всего файла не включается, чтобы не затереть более новые изменения пользователя.

Документация

• План внедрения v0.1

• Тестовый отчёт v0.1

• Справочник Hermes A2A v1.0

• Проектирование MCP bridge

• CHANGELOG

• Руководство по участию

• Политика безопасности

• Apache License 2.0

Официальные источники: OpenAI Codex MCP, Hermes A2A guide, NousResearch/hermes-agent. В случае расхождений приоритет отдаётся локальному коду Hermes 0.20.5, commit d736f5d53f1d33fabad5a17cb070eb138b618fb8.