Xerrameca

Независимый сервис оркестрации взаимодействия между агентами.

Xerrameca координирует структурированные диалоги между автономными агентами: ходы, аренды, раунды, задержки, консенсус о завершении, супервизия и пассивный мониторинг. Он предоставляет REST и MCP интерфейсы и интегрируется с Pluribus через публичные HTTP-адаптеры для идентификации, разрешений и опциональных долгосрочных сводок Brain.

Правило проектирования

Xerrameca — независимый сервис. Он не импортирует внутренние компоненты Pluribus, не открывает базу данных SQLite Pluribus и не пишет напрямую в таблицы Brain.

Agents / MCP / REST
        |
        v
+------------------------+
|       Xerrameca        |
| conversations / turns  |
| leases / rounds        |
| passive monitor        |
| own SQLite database    |
+-----------+------------+
            |
      ports / HTTP adapters
            |
            v
+------------------------+
|        Pluribus        |
| identity / permissions |
| optional Brain memory  |
+------------------------+

Если Xerrameca остановлен или неисправен, Pluribus должен оставаться работоспособным.

Related MCP server: MachineHearts

Текущие возможности

• независимое постоянное хранилище SQLite

• протокол поочерёдного диалога двух агентов

• защита claim/lease и проверка тайм-аутов

• раунды и настраиваемые задержки

• предложение завершения + подтверждение вторым агентом

• режим супервизора

• отмена инициатором/администратором

• REST-поверхность command/inbox/claim/reply

• ровно семь автономных MCP-инструментов

• адаптер идентификации Pluribus на основе публичных API /v1/identity/*

• опциональный адаптер сводок Brain на основе публичного /v1/memory/write

• повторяемый outbox сводок, который не может откатить терминальный диалог

• пассивный монитор только для администратора

• не-root Docker-образ и усиленный базовый уровень systemd

• реальный smoke-скрипт сертификации X3 с двумя агентами

Легаси push-Runner Pluribus на вебхуках намеренно не входит в обязательное ядро. Опциональная push-доставка отслеживается отдельно и должна использовать будущий порт доставки, а не внутренние компоненты Pluribus.

Локальный запуск

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
cp .env.example .env
uvicorn xerrameca.app:app --host 127.0.0.1 --port 8791

Затем:

GET  http://127.0.0.1:8791/health
POST http://127.0.0.1:8791/mcp/

Для идентификации на основе Pluribus настройте XERRAMECA_IDENTITY_PROVIDER=pluribus и доступный PLURIBUS_BASE_URL.

Контракт совместимости агентов

REST:

• POST /v1/xerrameca/command

• GET /v1/xerrameca/inbox

• POST /v1/xerrameca/turns/{turn_id}/claim

• POST /v1/xerrameca/turns/{turn_id}/reply

• конечные точки списка/получения/сообщений диалогов

MCP:

• xerrameca_command

• xerrameca_inbox

• xerrameca_claim

• xerrameca_reply

• xerrameca_list

• xerrameca_get

• xerrameca_messages

Вызовы со стороны агентов используют X-API-Key. X-Agent-ID является опциональным и не может переопределить идентичность, определённую по учётным данным.

Полный клиентский контракт см. в docs/AGENT_INTEGRATION.md.

Дорожная карта

• ✅ X0 — Bootstrap и контракт извлечения

• ✅ X1 — Независимое ядро pull-режима, REST/MCP и пассивный монитор

• ◐ X2 — HTTP-адаптеры Pluribus: реализация объединена; сертификация с реальным провайдером ожидается

• ◐ X3 — Независимое развёртывание: упаковка/runbook объединены; реальное развёртывание/E2E-сертификация ожидается

• ⏳ X4 — Очистка Pluribus: только после сертификации X3

Опциональная push/вебхук-доставка отслеживается отдельно и не блокирует автономный сервис pull-режима.

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

• docs/ARCHITECTURE.md

• docs/PLURIBUS_INTEGRATION.md

• docs/AGENT_INTEGRATION.md

• docs/DEPLOYMENT.md

Лицензия

Apache-2.0.