Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

id: ADR-007 title: Extraer la puerta de enlace en un proceso opcional independiente date: 2026-07-18 status: proposed relates-to:

  • ADR-002
  • docs/book/src/foundations/fnd-001-intentional-architecture.md
  • https://github.com/zeroclaw-labs/zeroclaw/issues/8691#issuecomment-5009706612
  • crates/zeroclaw-gateway
  • crates/zeroclaw-runtime/src/rpc

ADR-007: Extraer el Gateway en un Proceso Separado Opcional

Contexto

La superficie HTTP, WebSocket, webhook y dashboard de ZeroClaw ya cuenta con un crate dedicado zeroclaw-gateway. La aplicación principal todavía enlaza e inicia ese crate en proceso detrás de la feature gateway. El límite del crate mejora la propiedad del código, pero no proporciona aislamiento de procesos ni permite que un operador ejecute, reinicie, actualice u omita la superficie web de forma independiente del runtime del agente.

El runtime también tiene una superficie JSON-RPC, pero el contrato local estable completo, el transporte, el modelo de autenticación, la política de compatibilidad y la supervisión de procesos que necesita un gateway externo no se han publicado como un límite compatible único. Las costuras actuales del crate y RPC son, por tanto, pasos de migración útiles en lugar de prueba de que la extracción de procesos está completa.

Las alternativas son tratar el crate in-process con feature gates como la arquitectura final o convertir el gateway en un proceso opcional independiente conectado al runtime mediante un contrato IPC local explícito.

Decisión

Haremos que la puerta de enlace sea un proceso zeroclaw-gw separado y opcional.

El tiempo de ejecución del agente sigue siendo la autoridad en materia de ejecución de agentes, sesiones, memoria, configuración, herramientas, política de seguridad y demás estado del dominio. El gateway es propietario de los protocolos HTTP externos y de streaming, la entrega del dashboard, el emparejamiento y las preocupaciones orientadas al transporte, y la ingesta genérica de webhooks. Debe solicitar las operaciones de tiempo de ejecución a través del contrato IPC admitido, en lugar de acceder directamente al estado de tiempo de ejecución local del proceso.

El límite de IPC entre el runtime y el gateway debe estar autenticado, versionado y documentado. La selección del transporte puede variar según la plataforma, pero la conexión predeterminada debe permanecer local y no debe exponer de forma silenciosa la superficie de control del runtime en una interfaz pública.

La crate zeroclaw-gateway actual, en proceso y protegida por feature-gate, es una costura intermedia. Puede permanecer disponible mientras se desarrollan la paridad de IPC y el soporte del ciclo de vida del proceso, pero la nueva arquitectura no debe hacer que el acceso directo a las partes internas del runtime sea un requisito permanente del gateway.

Los operadores deben poder ejecutar el agente sin zeroclaw-gw. Un fallo o reinicio de la puerta de enlace no debe finalizar una ejecución del agente que, por lo demás, funcione correctamente.

Este ADR permanece propuesto hasta que se cumplan todas estas condiciones:

  • un binario zeroclaw-gw compatible se comunica con el runtime a través del contrato de IPC local documentado;
  • la frontera IPC cubre las capacidades de puerta de enlace requeridas para la experiencia de panel y API compatible sin acceso directo al estado local del proceso;
  • autenticación, negociación de versiones, reconexión, estado, inicio y comportamiento de apagado están implementados y documentados; y
  • una distribución de runtime compatible puede operar sin enlazar ni iniciar el servidor de gateway.

Consecuencias

Consecuencias positivas:

  • Los despliegues headless y restringidos pueden omitir por completo la superficie web.
  • Los fallos, reinicios y actualizaciones de Gateway están aislados de la ejecución del agente.
  • El contrato IPC proporciona a las aplicaciones de escritorio y otros clientes locales de confianza un límite de integración definido.
  • El tiempo de ejecución y la propiedad de la puerta de enlace son más fáciles de probar y razonar porque el acceso entre límites es explícito.

Consecuencias negativas:

  • La instalación, el inicio, la autenticación, el registro y el diagnóstico de múltiples procesos son más complejos que una llamada a función en proceso.
  • Los flujos y las cargas útiles grandes deben cruzar un límite serializado.
  • La política de compatibilidad es necesaria siempre que las versiones del tiempo de ejecución y de la puerta de enlace puedan diferir.
  • Hasta que se complete la paridad, los mantenedores deben admitir tanto la interfaz actual en proceso como el límite de proceso objetivo.

Referencias