ZEGA AI (Prototipo externo)

ZEGA AI es una plataforma fintech externa que se conecta a un demonio de puerta de enlace de ZeroClaw v0.8.x mediante un paquete puente de TypeScript (@zega/zeroclaw-bridge). El puente es un prototipo externo mantenido en el monorepo de ZEGA y no forma parte de ZeroClaw.

Estado: Prototipo. El puente se ha sometido a pruebas preliminares con módulos auxiliares locales (análisis de SemVer, jerarquías de errores y resiliencia sin conexión). Todavía no se han ejecutado pruebas de emparejamiento con ningún daemon activo ni pruebas de endpoints. La información siguiente describe la intención de diseño del puente, no una compatibilidad con entornos de producción verificada.

Emparejamiento

Nota sobre la configuración de la URL de la puerta de enlace: El cliente del puente usa http://127.0.0.1:4242 de forma predeterminada, mientras que el puerto predeterminado canónico de GatewayConfig de ZeroClaw es 42617. Al conectarse a un demonio local estándar de ZeroClaw, configure el cliente con la dirección de la puerta de enlace correspondiente:
const client = new ZeroClawGatewayClient({
  gatewayUrl: "http://127.0.0.1:42617",
});
Conectarse sin configurar el puerto de la puerta de enlace para que coincida con el demonio ZeroClaw activo hará que el puente informe de un estado sin conexión/inaccesible antes de que pueda producirse el emparejamiento.

Las puertas de enlace accesibles de forma remota deben usar HTTPS o un túnel autenticado (como WireGuard, Tailscale o un túnel SSH) en lugar de HTTP sin cifrar para proteger las credenciales de portador transmitidas en el encabezado Authorization.

El puente implementa los dos contratos de emparejamiento expuestos por la puerta de enlace de ZeroClaw y los prueba en orden:

Ruta mejorada: `POST /api/pair`

Acepta un cuerpo JSON:

{
  "code": <código de emparejamiento de 6 dígitos>,
  "device_name": "ZEGA AI Bridge",
  "device_type": "api-bridge"
}

Si se realiza correctamente, la puerta de enlace devuelve { "paired": true, "token": "<bearer>" }. El puente almacena el token para las solicitudes autenticadas posteriores.

Controlador upstream: api_pairing::submit_pairing_enhanced (crates/zeroclaw-gateway/src/api_pairing.rs).

Ruta heredada: `POST /pair`

Envía el código de emparejamiento en el encabezado X-Pairing-Code:

POST /pair
Content-Type: application/json
X-Pairing-Code: <6-digit code>

El puente recurre a esta ruta cuando el endpoint mejorado no está disponible o devuelve un estado que no es de éxito ni de límite de velocidad. Si el endpoint mejorado devuelve un error de límite de velocidad (RateLimitError), el puente vuelve a lanzar el error inmediatamente sin intentar la alternativa heredada.

Manejador upstream: handle_pair (crates/zeroclaw-gateway/src/lib.rs).

Arquitectura de puente

Componente	Rol
`ZeroClawGatewayClient`	Cliente HTTP con un tiempo de espera predeterminado de 5 segundos para las solicitudes y la comprobación de estado, cancelación mediante `AbortController` y reintentos automáticos con espera exponencial. Cambia a un estado de error sin conexión cuando no se puede acceder al demonio.
`ZeroClawAuthManager`	Gestiona el flujo de emparejamiento (mejorado → alternativa heredada) y genera encabezados `Authorization: Bearer <token>` para endpoints autenticados.
Matriz de versiones	Comprobación de versión en el cliente para los límites numéricos `>=0.8.0 <0.9.0` (objetivo `v0.8.3`). La función auxiliar actual del cliente elimina los sufijos de versiones preliminares antes de la comparación y evalúa los componentes numéricos (`major.minor.patch`). Este intervalo refleja la intención del diseño y no se ha verificado con un demonio en ejecución.

Qué cubre la prueba de humo

El puente incluye una prueba de humo (pnpm --filter @zega/zeroclaw-bridge test:smoke) con 18 aserciones que validan el siguiente comportamiento sin conexión y a nivel de unidad:

Análisis sintáctico y comparación de SemVer.
Límites de compatibilidad de versiones (compatible, demasiado antigua, supera el máximo).
Almacenamiento de tokens de Auth-manager, construcción del encabezado bearer y comportamiento sin conexión de getState().
Constructores y campos de errores de Gateway.

La prueba de humo no inicia un demonio de ZeroClaw, intercambia un código de emparejamiento ni llama a ningún endpoint de puerta de enlace a través de HTTP.

No ejercita las ramas de respaldo del emparejamiento de mejorado a heredado ni las de escalado del límite de velocidad.

Referencia externa

Para obtener detalles del código fuente y del monorepo, visita el repositorio de ZEGA AI o inspecciona el paquete bridge en el commit revisado f99104367a6b06815cf478120b247d042fa7b1a5俺去啦

Keyboard shortcuts

ZeroClaw Docs