ZEGA AI (Prototype externe)

ZEGA AI est une plateforme fintech externe qui se connecte à un démon de passerelle ZeroClaw v0.8.x via un paquet passerelle TypeScript (@zega/zeroclaw-bridge). La passerelle est un prototype externe maintenu dans le monorepo ZEGA et ne fait pas partie de ZeroClaw lui-même.

Statut : Prototype. Le pont a fait l’objet de tests de fumée avec des modules utilitaires locaux (analyse de SemVer, hiérarchies d’erreurs, résilience hors ligne). Aucun appairage avec un démon actif ni test de point de terminaison n’a encore été effectué. Les informations ci-dessous décrivent l’intention de conception du pont, et non une compatibilité en production vérifiée.

Appairage

Remarque sur la configuration de l’URL de la passerelle : le client de pont utilise par défaut http://127.0.0.1:4242, tandis que le port par défaut canonique de GatewayConfig de ZeroClaw est 42617. Lors de la connexion à un démon ZeroClaw local standard, configurez le client avec l’adresse de passerelle correspondante :
const client = new ZeroClawGatewayClient({
  gatewayUrl: "http://127.0.0.1:42617",
});
Se connecter sans configurer le port de la passerelle pour qu’il corresponde à celui du démon ZeroClaw actif amènera le pont à signaler un état hors ligne/injoignable avant que l’appairage puisse avoir lieu.

Les passerelles accessibles à distance devraient utiliser HTTPS ou un tunnel authentifié (tel que WireGuard, Tailscale ou un tunnel SSH) plutôt que HTTP en clair pour protéger les identifiants bearer transmis dans l’en-tête Authorization.

Le pont implémente les deux contrats d’appairage exposés par la passerelle ZeroClaw et les essaie dans l’ordre :

Route améliorée : `POST /api/pair`

Accepte un corps JSON :

{
  "code": <code de jumelage à 6 chiffres>,
  device_name: "ZEGA AI Bridge",
  "device_type": "api-bridge"
}

En cas de réussite, la passerelle renvoie { "paired": true, "token": "<bearer>" }. Le pont stocke le jeton pour les requêtes authentifiées ultérieures.

Gestionnaire en amont : api_pairing::submit_pairing_enhanced (crates/zeroclaw-gateway/src/api_pairing.rs).

Ancienne route : `POST /pair`

Envoie le code d’association dans l’en-tête X-Pairing-Code :

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

Le bridge utilise cette route de repli lorsque le point de terminaison amélioré est indisponible ou renvoie un statut d’échec qui n’est pas dû à une limitation de débit. Si le point de terminaison amélioré renvoie une erreur de limitation de débit (RateLimitError), le bridge relance immédiatement l’erreur sans tenter le mécanisme de repli historique.

Gestionnaire en amont : handle_pair (crates/zeroclaw-gateway/src/lib.rs).

Architecture de pont

Composant	Rôle
`ZeroClawGatewayClient`	Client HTTP avec un délai d’attente par défaut de 5 secondes pour les requêtes et la vérification de l’état de santé, l’annulation via `AbortController` et une nouvelle tentative automatique avec temporisation exponentielle. Bascule vers un état d’erreur hors connexion lorsque le démon est inaccessible.
`ZeroClawAuthManager`	Gère le flux d’appariement (version améliorée → solution de repli legacy) et génère des en-têtes `Authorization: Bearer <token>` pour les points de terminaison authentifiés.
Matrice des versions	Vérification de version côté client visant les limites numériques `>=0.8.0 <0.9.0` (cible `v0.8.3`). L’utilitaire client actuel supprime les suffixes de préversion avant la comparaison et évalue les composants numériques (`major.minor.patch`). Cette plage reflète l’intention de conception et n’a pas été vérifiée avec un démon actif.

Ce que couvre le test de fumée

Le bridge fournit un test de fumée (pnpm --filter @zega/zeroclaw-bridge test:smoke) comportant 18 assertions qui valident le comportement hors ligne / au niveau unitaire suivant :

Analyse et comparaison de SemVer.
Limites de compatibilité des versions (compatible, trop ancienne, dépasse le maximum).
Stockage des jetons d’Auth-manager, construction de l’en-tête bearer et comportement hors ligne de getState().
Constructeurs et champs d’erreur de la passerelle.

Le test de fumée ne démarre pas de démon ZeroClaw, n’échange pas de code d’appariement et n’appelle aucun point de terminaison de passerelle via HTTP.

Cela ne couvre pas les branches de secours d’appariement enhanced-to-legacy ni d’escalade de limitation de débit.

Référence externe

Pour le code source et les détails du monorepo, consultez le dépôt ZEGA AI ou inspectez le package bridge au commit examiné f99104367a6b06815cf478120b247d042fa7b1a5.

Keyboard shortcuts

ZeroClaw Docs