Metadata-Version: 2.4
Name: hermes-glassbox
Version: 0.1.0
Summary: Adaptateur Hermes <> Glassbox — pre-flight bidirectionnel + timeline.
Project-URL: Homepage, https://github.com/glassbox-org/hermes-plugin
Project-URL: Issues, https://github.com/glassbox-org/hermes-plugin/issues
Author: JMR Digital
License: MIT
License-File: LICENSE
Keywords: agent,ai-act,glassbox,hermes
Requires-Python: >=3.11
Requires-Dist: glassbox-py<0.2,>=0.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# hermes-glassbox

> Adaptateur [Glassbox](https://glassbox.call-for-me.com) pour [Hermes](https://github.com/NousResearch/hermes-agent) — pre-flight bidirectionnel + timeline temps réel.

[![PyPI](https://img.shields.io/pypi/v/hermes-glassbox.svg)](https://pypi.org/project/hermes-glassbox/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## TL;DR (Windows)

```powershell
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` :

```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

```bash
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.
