hermes-glassbox 0.1.0

Adaptateur Hermes <> Glassbox — pre-flight bidirectionnel + timeline.

hermes-glassbox

Adaptateur Glassbox pour Hermes — pre-flight bidirectionnel + timeline temps réel.

TL;DR (Windows)

pip install hermes-glassbox

$env:GLASSBOX_API_URL = "https://glassbox.call-for-me.com"
$env:GLASSBOX_API_TOKEN = "gbx_<le_token_généré_dans_la_PWA>"
$env:GLASSBOX_AGENT_NAME = "Hermes-Terminal"

hermes-glassbox status   # vérifie la connexion
hermes-glassbox test     # pousse un event de test -> timeline Glassbox
hermes                    # Hermes auto-discover le plugin via entry_points

A partir de la chaque tool exécuté par Hermes est tracé dans Glassbox, et les actions critiques (bash, delete_file, send_telegram, etc.) déclenchent un pre-flight bloquant que tu peux approuver/rejeter depuis la PWA — y compris depuis ton mobile via push notif.

Comment générer un token

1. Connecte-toi a https://glassbox.call-for-me.com
2. Dashboard -> Tokens agents -> Nouveau token
3. Nomme-le ("Hermes Windows JM"), copie-le immédiatement (affiché 1x seulement)
4. Stocke-le dans une variable d'env GLASSBOX_API_TOKEN — jamais en clair dans un fichier

Variables d'environnement

Variable	Requis	Défaut	Description
GLASSBOX_API_URL	oui	---	https://glassbox.call-for-me.com
GLASSBOX_API_TOKEN	oui	---	Token généré côté PWA
GLASSBOX_AGENT_NAME	non	Unknown-Agent	Affiché dans la timeline
GLASSBOX_FAIL_MODE	non	reject	reject (sécurité) ou log_only (dev)

Configuration TOML alternative

~/.glassbox/config.toml :

[glassbox]
api_url = "https://glassbox.call-for-me.com"
api_token = "${GLASSBOX_TOKEN}"  # interpolation env, JAMAIS le token en clair
agent_name = "Hermes-Terminal"
fail_mode = "reject"

Mapping built-in tools Hermes

Tool Hermes	action_type Glassbox
write_file	file_write
edit_file	file_write
delete_file	file_delete
bash	shell_command
python	code_execution
web_fetch	network_read
http_request	network_read ou network_write selon méthode
send_telegram	external_message
autres	tool_call_unknown (fallback safe)

Pour tools custom (MCP, plugin maison) : fallback tool_call_unknown avec payload brut tronqué 500 chars. Tu peux pousser des metadata.* custom utilisables dans tes regles d'autonomie.

Commandes CLI

hermes-glassbox status            # connectivité + agent + panic_mode + count regles
hermes-glassbox test              # smoke test event bout en bout
hermes-glassbox panic on / off    # affiche les instructions PWA pour toggle

Compatibilité Hermes

Ce plugin suppose que Hermes expose un système de hooks lifecycle via ctx.on(<event>). Si l'API Hermes diffère (sous-classe AIAgent, registry, async middleware), le module hooks.py documente un fallback monkey-patch. Vérifier la version Hermes installée et consulter la doc officielle en cas de problème de discovery.

Le namespace entry_points utilisé est hermes.plugins. Si Hermes utilise un namespace différent, modifier [project.entry-points] dans pyproject.toml.

Troubleshooting

Symptome	Cause probable	Fix
[KO] Config invalide	env vars manquantes	echo $env:GLASSBOX_API_TOKEN (PowerShell)
401 Unauthorized	token révoqué ou faute de frappe	Régénérer token dans PWA
Glassbox unreachable	DNS, firewall, TLS	curl -I $env:GLASSBOX_API_URL coté machine Hermes
Hermes ignore le plugin (rien en log)	entry_points pas découverts	pip show hermes-glassbox puis vérifier Entry-points
Action critique non bloquante	fail_mode=log_only	Repasser sur reject (défaut)
Tous les preflights deviennent pending	mode panique activé coté PWA	Désactiver dans Dashboard ou via curl session-user

Sécurité

• Token jamais loggé.
• HTTPS obligatoire (validation cert TLS stricte).
• Heuristique de redaction password / token / secret / api_key / auth / authorization AVANT envoi.
• Logs : stderr uniquement, pas de fichier par défaut.

Licence

MIT.