Xerrameca

Servicio independiente de orquestación entre agentes.

Xerrameca coordina conversaciones estructuradas entre agentes autónomos: turnos, concesiones, rondas, demoras, consenso de finalización, supervisión y monitoreo pasivo. Expone interfaces REST y MCP y se integra con Pluribus a través de adaptadores HTTP públicos para identidad, permisos y resúmenes opcionales de Brain a largo plazo.

Regla de diseño

Xerrameca es un servicio independiente. No importa las partes internas de Pluribus, ni abre la base de datos SQLite de Pluribus, ni escribe directamente en las tablas de 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  |
+------------------------+

Si Xerrameca se detiene o falla, Pluribus debe permanecer saludable.

Related MCP server: MachineHearts

Capacidades actuales

• Persistencia independiente en SQLite

• Protocolo de diálogo alterno entre dos agentes

• Protección de reclamación/concesión y comprobaciones de tiempo de espera

• Rondas y retrasos configurables

• Propuesta de finalización + confirmación del segundo agente

• Modo supervisor

• Cancelación por iniciador/administrador

• Superficie REST de comando/buzón/reclamación/respuesta

• Exactamente siete herramientas MCP independientes

• Adaptador de identidad de Pluribus que utiliza las API públicas /v1/identity/*

• Adaptador opcional de resúmenes de Brain que utiliza /v1/memory/write público

• Bandeja de salida de resúmenes reintentable que no puede revertir una conversación terminal

• Monitor pasivo solo para administradores

• Imagen Docker no root y línea base systemd endurecida

• Script de prueba de humo real de certificación X3 con dos agentes

El Runner de push por webhook heredado de Pluribus no forma parte intencionadamente del núcleo obligatorio. La entrega push opcional se realiza un seguimiento por separado y debe utilizar un puerto de entrega futuro en lugar de las partes internas de Pluribus.

Ejecutar localmente

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

Luego:

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

Para la identidad respaldada por Pluribus, configure XERRAMECA_IDENTITY_PROVIDER=pluribus y una PLURIBUS_BASE_URL accesible.

Contrato de compatibilidad de agentes

REST:

• POST /v1/xerrameca/command

• GET /v1/xerrameca/inbox

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

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

• Endpoints de lista/obtención/mensajes de conversación

MCP:

• xerrameca_command

• xerrameca_inbox

• xerrameca_claim

• xerrameca_reply

• xerrameca_list

• xerrameca_get

• xerrameca_messages

Las llamadas orientadas a agentes usan X-API-Key. X-Agent-ID es opcional y no puede sobrescribir la identidad resuelta por la credencial.

Consulte docs/AGENT_INTEGRATION.md para conocer el contrato completo del cliente.

Hoja de ruta

• ✅ X0 — Contrato de arranque y extracción

• ✅ X1 — Núcleo independiente en modo pull, REST/MCP y monitor pasivo

• ◐ X2 — Adaptadores HTTP de Pluribus: implementación fusionada; certificación con proveedor real pendiente

• ◐ X3 — Despliegue independiente: empaquetado/runbook fusionado; certificación de despliegue real/E2E pendiente

• ⏳ X4 — Limpieza de Pluribus: solo después de la certificación X3

La entrega opcional push/webhook se realiza un seguimiento por separado y no bloquea el servicio independiente en modo pull.

Documentación

• docs/ARCHITECTURE.md

• docs/PLURIBUS_INTEGRATION.md

• docs/AGENT_INTEGRATION.md

• docs/DEPLOYMENT.md

Licencia

Apache-2.0.