feat(stt): actions cluster via Hermes — contexte « agent » + exécuteur hermes-exec (#42)

Asa peut AGIR sur le homelab (l'autre moitié de la vision), via le vrai agent Hermes,
profil par défaut, tous ses outils — avec confirmation et jeton.

Découverte : Hermes n'a pas d'API HTTP (appli TUI), mais un mode one-shot `hermes -z
"<prompt>" --yolo`. On s'appuie dessus.

storage-01 — exécuteur :
- tools/hermes-exec/server.py : service HTTP qui lance `hermes -z --yolo` en user hermes,
  derrière un jeton Bearer (compare_digest), timeout + audit, une action à la fois.
- rôle Ansible hermes_exec : systemd (User=hermes, env hermes-agent), jeton via
  EnvironmentFile 0640 (Vault vault_hermes_exec_token) ; ajouté au playbook storage-01.

STT-server (0.5.0 → 0.6.0) :
- agent.py : pont vers hermes-exec (jeton) + détection confirme/annule.
- contexts.py : contexte « agent » (court-circuite le LLM).
- app.py : flux dédié — handshake 2 temps par session (pending action) → sur « confirme »,
  appelle hermes-exec ; « annule » annule. /v1/contexts masque « agent » si désactivé.
- config : STT_ACTIONS_ENABLED (opt-in, défaut false) + URL + jeton (secret k8s).
- deployment : env actions + secret stt-server-secrets/hermes-exec-token (optionnel).

Sécurité : opt-in désactivé par défaut ; jeton obligatoire (sinon contexte caché + exécuteur
refuse tout) ; --yolo atteint seulement jeton+confirmation en main ; audit storage-01.
Client : AUCUN changement (le contexte « agent » apparaît tout seul dans le sélecteur).

Validé en local : exécuteur (401 sans/mauvais jeton, exec avec bon jeton via echo),
handshake serveur (TestClient : confirme→exécute, annule→annule, agent masqué si OFF).

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

stt/server/stt_server/__init__.py

@@ -1,3 +1,3 @@
 """STT-server — orchestrateur AI in-cluster pour les clients STT."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"

stt/server/stt_server/agent.py

@@ -0,0 +1,55 @@
+"""Pont vers hermes-exec (storage-01) — exécution d'actions via le vrai agent Hermes.
+
+Le STT-server appelle hermes-exec **après** confirmation vocale de l'utilisateur. Le
+jeton d'auth (env, depuis un secret k8s) protège l'endpoint. Tout est best-effort :
+une erreur renvoie un message parlable, jamais une exception.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+import httpx
+
+from stt_server.config import settings
+
+# Mots de (dé)confirmation pour le handshake en 2 temps.
+_CONFIRM = {"confirme", "confirmer", "oui", "vas-y", "vas y", "valide", "ok", "go",
+            "d'accord", "daccord", "c'est bon", "cest bon", "fais-le", "fais le"}
+_CANCEL = {"annule", "annuler", "non", "stop", "laisse tomber", "laisse",
+           "oublie", "abandonne"}
+
+
+def _norm(s: str) -> str:
+    s = unicodedata.normalize("NFKD", str(s))
+    s = "".join(c for c in s if not unicodedata.combining(c))
+    return " ".join(s.lower().split()).strip(" .!?")
+
+
+def is_confirmation(text: str) -> bool:
+    return _norm(text) in _CONFIRM
+
+
+def is_cancellation(text: str) -> bool:
+    return _norm(text) in _CANCEL
+
+
+async def run_action(prompt: str) -> str:
+    """Exécute `prompt` via hermes-exec ; renvoie la sortie de l'agent (ou une erreur lisible)."""
+    if not settings.hermes_exec_token:
+        return "Les actions ne sont pas configurées côté serveur (jeton manquant)."
+    url = settings.hermes_exec_url.rstrip("/") + "/exec"
+    headers = {"Authorization": f"Bearer {settings.hermes_exec_token}"}
+    try:
+        async with httpx.AsyncClient(timeout=settings.hermes_exec_timeout) as c:
+            r = await c.post(url, json={"prompt": prompt}, headers=headers)
+        if r.status_code == 401:
+            return "Refusé par l'exécuteur Hermes (jeton invalide)."
+        r.raise_for_status()
+        data = r.json()
+        out = (data.get("output") or "").strip()
+        return out or "Action effectuée (aucune sortie)."
+    except httpx.HTTPError:
+        return "Je n'arrive pas à joindre l'exécuteur Hermes pour le moment."
+    except ValueError:
+        return "Réponse inattendue de l'exécuteur Hermes."

stt/server/stt_server/app.py

@@ -19,6 +19,7 @@ from stt_server import __version__
 from stt_server import brain
 from stt_server.brain import ask as brain_ask
 from stt_server.config import settings
+from stt_server import agent
 from stt_server.contexts import CONTEXTS, assemble, get_context
 from stt_server.knowledge import Knowledge
 from stt_server.longterm import LongTermMemory
@@ -39,6 +40,13 @@ sessions = SessionStore()
 longterm = LongTermMemory() if settings.memory_longterm else None
 knowledge = Knowledge() if settings.docs_rag else None
 
+# Contexte « agent » : action en attente de confirmation, par session.
+pending_actions: dict[str, str] = {}
+
+
+def _actions_available() -> bool:
+    return settings.actions_enabled and bool(settings.hermes_exec_token)
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
@@ -91,6 +99,8 @@ async def v1_contexts() -> dict:
         "contexts": [
             {"id": c.id, "label": c.label, "icon": c.icon, "description": c.description}
             for c in CONTEXTS.values()
+            # le contexte « agent » n'apparaît que si les actions sont activées + jeton
+            if c.id != "agent" or _actions_available()
         ],
     }
 
@@ -122,6 +132,44 @@ async def v1_reset(req: AskRequest) -> dict:
     return {"status": "reset"}
 
 
+def _agent_context_debug(detail: dict) -> dict:
+    """Structure de visualisation pour le contexte agent (transparence du handshake)."""
+    return {
+        "id": "agent", "label": "Agent (actions)", "icon": "🤖",
+        "system_prompt": "Flux agent : la demande est confirmée puis exécutée par "
+        "le vrai agent Hermes (hermes -z --yolo).",
+        "blocks": [{"source": "agent", "title": "Action", "text": str(detail)}],
+        "docs": [], "memories": [],
+    }
+
+
+async def _handle_agent(req: AskRequest, text: str) -> AskReply:
+    """Handshake de confirmation puis exécution via hermes-exec. Court-circuite le LLM."""
+    sid = req.session_id or "anon"
+    if not _actions_available():
+        return AskReply(
+            reply="Les actions sont désactivées côté serveur.",
+            model=settings.model, context_id="agent",
+            context=_agent_context_debug({"disabled": True}),
+        )
+    pending = pending_actions.get(sid)
+    if pending and agent.is_confirmation(text):
+        pending_actions.pop(sid, None)
+        out = await agent.run_action(pending)
+        log.info("agent EXEC sid=%s prompt=%r", sid, pending[:120])
+        return AskReply(reply=out, model=settings.model, context_id="agent",
+                        context=_agent_context_debug({"executed": pending, "result": out[:300]}))
+    if pending and agent.is_cancellation(text):
+        pending_actions.pop(sid, None)
+        return AskReply(reply="C'est annulé.", model=settings.model, context_id="agent",
+                        context=_agent_context_debug({"cancelled": pending}))
+    # nouvelle demande (ou remplacement) → on stocke et on demande confirmation
+    pending_actions[sid] = text
+    reply = f"Tu veux que j'exécute : « {text} » ? Dis « confirme » ou « annule »."
+    return AskReply(reply=reply, model=settings.model, context_id="agent",
+                    context=_agent_context_debug({"pending": text}))
+
+
 @app.post("/v1/ask", response_model=AskReply)
 async def v1_ask(req: AskRequest, background: BackgroundTasks) -> AskReply:
     text = req.text.strip()
@@ -134,6 +182,9 @@ async def v1_ask(req: AskRequest, background: BackgroundTasks) -> AskReply:
             detail=f"modèle '{model}' non autorisé ; dispo : {settings.allowed_models}",
         )
     ctx = get_context(req.context)
+    # Contexte « agent » : flux dédié (confirmation 2 temps → hermes-exec), sans LLM.
+    if ctx.id == "agent":
+        return await _handle_agent(req, text)
     t0 = time.perf_counter()
     history = sessions.history(req.session_id) if req.session_id else None
     # recall : timeout serré, dégrade vite ; renvoie aussi le vecteur (réutilisé ci-dessous)

stt/server/stt_server/config.py

@@ -78,5 +78,12 @@ class Settings:
     prometheus_url: str = os.getenv("STT_PROMETHEUS_URL", "http://prometheus.lab.local")
     alertmanager_url: str = os.getenv("STT_ALERTMANAGER_URL", "http://alertmanager.lab.local")
 
+    # Actions via Hermes (contexte « agent ») — OPT-IN, désactivé par défaut.
+    # Le contexte « agent » n'est exposé que si actions_enabled ET un jeton est présent.
+    actions_enabled: bool = os.getenv("STT_ACTIONS_ENABLED", "false").lower() == "true"
+    hermes_exec_url: str = os.getenv("STT_HERMES_EXEC_URL", "http://192.168.10.1:9096")
+    hermes_exec_token: str = os.getenv("STT_HERMES_EXEC_TOKEN", "")
+    hermes_exec_timeout: float = float(os.getenv("STT_HERMES_EXEC_TIMEOUT", "130"))
+
 
 settings = Settings()

stt/server/stt_server/contexts.py

@@ -71,6 +71,15 @@ CONTEXTS: dict[str, Context] = {
         "Tu fais de la LECTURE SEULE : tu n'exécutes aucune action.",
         sources=("cluster", "docs"),
     ),
+    # Contexte « agent » : court-circuite le LLM — la demande est confirmée puis
+    # exécutée par le vrai agent Hermes (hermes-exec). Géré entièrement dans app.py
+    # (handshake), pas via assemble(). Exposé seulement si actions_enabled + jeton.
+    "agent": Context(
+        id="agent", label="Agent (actions)", icon="🤖",
+        description="Demander à Hermes d'AGIR sur le homelab (confirmation requise).",
+        system_prompt="",  # non utilisé : flux dédié
+        sources=(),
+    ),
 }
 
 # Titres des blocs injectés (visualiseur + prompt)