sinfallas/hermes-opencode-bridge repository overview

⁠Hermes-OpenCode Bridge 🌉🤖

Esta imagen fue diseñada para trabajar dentro del proyecto: https://github.com/tecno-consultores/llm-lab⁠

Si desea probar solo la integración clone el repositorio: https://github.com/tecno-consultores/hermes-opencode-bridge⁠

Y ejecute el comando:

docker compose -f docker-compose.yml --env-file env.example --profile acp-orchestrator --profile hermes --profile opencode up -d

Un microservicio ultrarrápido construido con FastAPI y uv que funciona como servidor nativo Model Context Protocol (MCP) y puente de comunicación asíncrona entre Hermes (Agente Manager) y OpenCode (Agente Worker).

Esta nueva arquitectura resuelve los bloqueos de interfaz ("abrazos mortales") procesando las tareas pesadas en segundo plano. El puente expone la herramienta delegar_a_opencode nativamente a través de MCP (vía SSE), permitiendo a Hermes delegar tareas de programación y ejecución en terminal dentro de un entorno Dockerizado (/workspace), manteniendo una capa de auditoría de seguridad interactiva.

Para ejecutar la integración completa ejecute el siguiente comando:

docker compose -f docker-compose.yml --env-file env.example --profile acp-orchestrator --profile hermes --profile opencode up -d

⁠✨ Características Principales

• Protocolo MCP Híbrido (SSE): Soporte total para la especificación Model Context Protocol con aislamiento de sesiones (UUID) y ruteo a prueba de fallos, compatible con versiones estrictas del SDK de NousResearch.
• Ejecución Zero-Blocking Asíncrona: Las tareas delegadas liberan inmediatamente la interfaz de Hermes (HTTP 202 Accepted), ejecutando OpenCode en background y permitiendo paralelismo real.
• Comunicación Nativa ACP: Habla directamente con el servidor de OpenCode a través de flujos stdio usando docker exec.
• Auditoría de Seguridad Avanzada (Safety Layer): Intercepta peticiones de permisos de OpenCode y realiza una auditoría de seguridad consultando al motor de Hermes. Implementa un ciclo de retroalimentación de dos fases, el cual extrae decisiones y sugerencias de mitigación en formato JSON para inyectarlas directamente en la memoria del agente.
• Auto-Ensamblaje "Zero-Touch": Capacidad para que el agente manager detecte y registre la herramienta por sí mismo en caliente.

⁠🏗️ Arquitectura del Flujo Asíncrono

1. Auto-Registro: Hermes detecta la ausencia del servidor MCP y se auto-configura vía CLI.
2. Handshake MCP: Hermes se conecta al endpoint /sse. El Bridge responde adaptándose dinámicamente a la versión del protocolo y entregando la herramienta delegar_a_opencode.
3. Delegación (Non-Blocking): El usuario pide una tarea. Hermes invoca la herramienta. El Bridge devuelve un éxito inmediato para liberar la UI y levanta el túnel hacia OpenCode en segundo plano.
4. Auditoría y Retroalimentación: Si OpenCode intenta ejecutar una acción destructiva, solicita permiso. El orquestador pausa el flujo y consulta a Hermes. Si la acción es rechazada, se extrae una directiva de mitigación en formato estructurado y se inyecta dinámicamente como un nuevo prompt en la sesión de OpenCode para que el agente adapte su estrategia operativa.

⁠🚀 Instalación y Despliegue

Integre el orquestador en su stack usando Docker Compose. Asegúrese de que el contenedor de OpenCode esté en la misma red o entorno.

services:
  acp-orchestrator:
    image: sinfallas/hermes-opencode-bridge:latest
    container_name: acp-orchestrator
    ports:
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      opencode:
        condition: service_started

⁠🔌 Integración Automática (System Prompt)

Para lograr un despliegue "Zero-Touch" donde Hermes se conecte a este orquestador de manera autónoma, configure la siguiente variable de entorno (learning_acp_orchestrator) en su contenedor de Hermes. Esta instrucción incluye el protocolo de auto-ensamblaje, la separación de roles y la exigencia de respuestas estructuradas en JSON para la auditoría:

Role: Lead DevOps Manager. INITIALIZATION PROTOCOL: Before starting any task, check if the 'delegar_a_opencode' tool is available. If NOT, use your local terminal to execute exactly: '/opt/hermes/.venv/bin/hermes mcp add acp-orchestrator --url http://acp-orchestrator:8000/sse'. OPERATING RULES: You are the orchestrator. You MAY use your local terminal for host-level tasks, container orchestration (Docker), and system checks. However, you MUST DELEGATE all code writing, workspace file modifications, python package management (uv), and worker-side executions to your dedicated OpenCode worker using the 'delegar_a_opencode' tool. Provide the worker with highly detailed, step-by-step instructions. IMPORTANT SECURITY AUDIT: You monitor the worker. If prompted to evaluate a potentially dangerous action from OpenCode, switch to auditor mode. Evaluate its safety and respond ONLY with a valid JSON object containing two keys: 'decision' (must be 'approved' or 'rejected') and 'suggestion' (feedback or alternative action, leave empty if approved). Do not include markdown formatting.

⁠🧪 Verificación de Conexión

Una vez levantado el entorno, usted puede confirmar que el puente está escuchando el protocolo MCP nativo comprobando el endpoint híbrido:

# Debería devolver HTTP 200 y las cabeceras de protocolo MCP inyectadas
curl -I -X HEAD http://localhost:8000/sse

Para reporta una falla o solicitar soporte:

• https://github.com/tecno-consultores/hermes-opencode-bridge/issues⁠