failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/fr/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "Métriques de performance"
+description: "Détectez à l'instant précis où vos modèles, outils ou hooks ralentissent ou font grimper la facture, et interceptez un pic de latence en queue de distribution avant que vos utilisateurs ne le ressentent."
+---
+
+
+Détectez à l'instant précis où vos modèles, outils ou hooks ralentissent ou font grimper la facture, et interceptez un pic de latence en queue de distribution avant que vos utilisateurs ne le ressentent. Trois pages dédiées transforment les mesures brutes en p50, p95 et p99 lisibles en un coup d'œil.
+
+![La page Models affichant une carte de chaleur de latence, une bande de percentiles et des chiffres de tokens, coût et fenêtre de contexte par modèle](/agenteye/images/models.png)
+*La page Models : une carte de chaleur de latence, une bande de percentiles et, par modèle, le nombre de tokens, le coût estimé et le remplissage de la fenêtre de contexte.*
+
+## Arrêtez de laisser les moyennes masquer vos pires exécutions
+
+Un chiffre de latence moyenne est rassurant et inutile : il lisse le seul appel sur cinquante qui bloque et réveille votre équipe d'astreinte à 2h du matin. Les pages Models, Tools et Hooks refusent de faire ça. Chacune partage la même structure, à apprendre une seule fois :
+
+- Un **sparkline à 24 bins** pour saisir la tendance d'un coup d'œil : la situation empire-t-elle ?
+- Une **bande de métriques vitales** avec les latences p50, p95 et p99, pour voir côte à côte l'exécution typique et la queue de distribution.
+- Une **carte de chaleur de latence**, 24 intervalles temporels croisés avec des buckets de latence, qui indique *quand* les appels lents se sont concentrés.
+- Une **bande de percentiles** : une ligne p50 avec des rubans ombrés p25–p75 et p10–p90, et des points p99, afin que l'écart reste visible plutôt que noyé dans une moyenne.
+
+Un réticule de survol partagé relie la carte de chaleur et la bande, de sorte qu'un pic en queue de distribution s'aligne dans le temps sur les deux vues plutôt que de se cacher derrière une unique ligne de moyenne. Retrouvez ces trois pages dans la section **observe** de votre tableau de bord, chacune limitée à votre organisation et filtrable par plage de dates, environnement, agent et session.
+
+## Models : voyez exactement ce que chaque modèle vous coûte
+
+La page Models (illustrée ci-dessus) répond aux deux questions qu'une facture soulève invariablement : quel modèle, et combien. En plus de la vue de latence partagée, elle ajoute la **consommation de tokens par modèle**, le **coût estimé** et le **remplissage de la fenêtre de contexte**, afin que la croissance incontrôlée des prompts et une compaction imminente soient visibles avant de vous surprendre.
+
+Failproof AI Observability reconnaît automatiquement les identifiants de modèles courants. Si une fenêtre semble incorrecte, ou si vous utilisez un modèle privé, corrigez-la ou ajoutez-en un depuis **Settings**, dans **model context windows** — les indicateurs de remplissage se mettront à jour en conséquence.
+
+## Tools : distinguez la lenteur de la défaillance
+
+Un appel d'outil peut être lent, ou il peut échouer silencieusement — et vous voulez savoir lequel en quelques secondes, pas après avoir fouillé des logs.
+
+![La page Tools affichant la carte de chaleur et la bande de percentiles partagées, à côté d'une répartition succès/échecs et d'une barre de distribution des outils](/agenteye/images/tools.png)
+*La page Tools : la même carte de chaleur et bande de percentiles, plus une répartition succès/échecs et une barre de distribution des outils.*
+
+En complément de la vue de latence partagée, la page Tools ajoute une **répartition succès/échecs** et une **barre de distribution des outils**, afin de voir en un coup d'œil quels outils vous sollicitez le plus et lesquels grignotent votre budget d'erreurs.
+
+## Hooks : identifiez le hook et le déclencheur exacts
+
+Quand un hook de cycle de vie alourdit une exécution, constater que « les hooks sont lents » n'est pas exploitable. La page Hooks vous amène directement à celui qui pose problème.
+
+![La page Hooks affichant la latence décomposée par nom de hook et événement déclencheur, sur la carte de chaleur et la bande de percentiles partagées](/agenteye/images/hooks.png)
+*La page Hooks : la latence décomposée par nom de hook et événement déclencheur.*
+
+Au-dessus de la même carte de chaleur et bande de percentiles, la page Hooks décompose l'activité par **nom de hook** et **événement déclencheur**, afin de cibler précisément le hook unique et l'événement unique qui nécessitent votre attention.
+
+## Voir aussi
+
+- [Flux d'événements](/fr/agenteye/event-stream) : la trace en direct, colorée, de chaque événement.
+- [Sessions](/fr/agenteye/sessions) : regroupez les événements en une ligne par exécution et ouvrez son graphe d'exécution.
+- [Suivi des erreurs](/fr/agenteye/error-tracking) : une surface de triage unique pour tout ce que le tableau de bord affiche en rouge.
+- [Tableaux de bord](/fr/agenteye/dashboards) : vues agrégées sur l'ensemble de votre flotte.

package/.next/standalone/docs-old/fr/architecture.mdx

@@ -0,0 +1,332 @@
+---
+title: Architecture
+description: "Fonctionnement interne du gestionnaire de hooks, du chargement de la configuration et de l'évaluation des politiques"
+icon: sitemap
+---
+
+Ce document explique le fonctionnement interne de failproofai : comment le système de hooks intercepte les appels d'outils des agents, comment la configuration est chargée et fusionnée, comment les politiques sont évaluées, et comment le tableau de bord surveille l'activité des agents.
+
+---
+
+## Vue d'ensemble
+
+failproofai comporte deux sous-systèmes indépendants :
+
+1. **Gestionnaire de hooks** - Un sous-processus CLI rapide que Claude Code invoque à chaque appel d'outil d'un agent. Il évalue les politiques et retourne une décision.
+2. **Agent Monitor (Tableau de bord)** - Une application web Next.js permettant de surveiller les sessions des agents et de gérer les politiques.
+
+Les deux sous-systèmes partagent des fichiers de configuration situés dans `~/.failproofai/` et dans le répertoire `.failproofai/` du projet, mais ils s'exécutent en tant que processus distincts et ne communiquent que via le système de fichiers.
+
+---
+
+## Gestionnaire de hooks
+
+### Intégration avec Claude Code
+
+Lorsque vous exécutez `failproofai policies --install`, des entrées comme celle-ci sont écrites dans `~/.claude/settings.json` :
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code invoque ensuite `failproofai --hook PreToolUse` en tant que sous-processus avant chaque appel d'outil, en transmettant une charge utile JSON sur stdin.
+
+### Format de la charge utile
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
+  "cwd": "/home/user/myproject",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Bash",
+  "tool_input": { "command": "sudo apt install nodejs" }
+}
+```
+
+Pour les événements `PostToolUse`, la charge utile contient également `tool_result` avec la sortie de l'outil.
+
+Le gestionnaire applique une limite de 1 Mo sur stdin. Les charges utiles dépassant cette taille sont ignorées et toutes les politiques autorisent implicitement.
+
+### Format de la réponse
+
+**Refus (PreToolUse) :**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Refus (PostToolUse) :**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruction (tout événement sauf Stop) :**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Instruction pour l'événement Stop :**
+- Code de sortie : `2`
+- La raison est écrite sur stderr (et non sur stdout)
+
+**Autorisation :**
+- Code de sortie : `0`
+- stdout vide
+
+**Autorisation avec message :**
+
+`allow(message)` permet à une politique d'envoyer du contexte informatif à Claude même lorsque l'opération est autorisée. Le gestionnaire de hooks écrit le JSON suivant sur **stdout** (et non dans un fichier de configuration — il s'agit de la réponse du gestionnaire à Claude Code, au même titre que les réponses de refus et d'instruction ci-dessus) :
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Code de sortie : `0` (l'opération est autorisée)
+- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont concaténés avec des sauts de ligne dans une seule chaîne `additionalContext`
+- Si aucune politique ne fournit de message, stdout est vide (comportement inchangé)
+
+### Pipeline de traitement
+
+`src/hooks/handler.ts` implémente l'intégralité du pipeline :
+
+```text
+stdin JSON
+  → parse payload (max 1 MB)
+  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← merges project + local + global config
+  → register enabled builtin policies with resolved params
+  → load custom policies from customPoliciesPath (if set)
+  → register custom policies into policy registry
+  → evaluate all policies (builtins first, then custom)
+      → first deny short-circuits
+      → instruct decisions accumulate
+      → allow messages accumulate
+  → write JSON decision to stdout
+  → persist event to ~/.failproofai/hook-activity/current.jsonl
+  → exit
+```
+
+L'ensemble du processus s'exécute en moins de 100 ms pour des charges utiles classiques, sans aucun appel à un LLM.
+
+---
+
+## Chargement de la configuration
+
+`src/hooks/hooks-config.ts` implémente le chargement de la configuration sur trois portées.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← projet   (priorité la plus haute)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global   (priorité la plus basse)
+```
+
+Logique de fusion :
+- `enabledPolicies` - union dédupliquée des trois fichiers
+- `policyParams` - par clé de politique, le premier fichier qui la définit l'emporte entièrement
+- `customPoliciesPath` - le premier fichier qui la définit l'emporte
+- `llm` - le premier fichier qui la définit l'emporte
+
+Le tableau de bord web utilise `readHooksConfig()` (portée globale uniquement) pour la lecture et l'écriture, car il n'est pas invoqué avec un répertoire de travail de projet.
+
+---
+
+## Évaluation des politiques
+
+`src/hooks/policy-evaluator.ts` exécute les politiques dans l'ordre.
+
+Pour chaque politique :
+
+1. Recherche du schéma `params` de la politique (si elle en possède un).
+2. Lecture de `policyParams[policy.name]` depuis la configuration fusionnée.
+3. Fusion des valeurs fournies par l'utilisateur sur les valeurs par défaut du schéma pour produire `ctx.params`.
+4. Appel de `policy.fn(ctx)` avec le contexte résolu.
+5. Si le résultat est `deny`, arrêt immédiat et retour de cette décision.
+6. Si le résultat est `instruct`, accumulation du message et poursuite.
+7. Si le résultat est `allow`, passage à la politique suivante.
+
+Après exécution de toutes les politiques :
+- Si un `deny` a été retourné, la réponse de refus est émise.
+- Si des retours `instruct` ont été collectés, une unique réponse d'instruction est émise avec tous les messages joints.
+- Sinon, une réponse d'autorisation est émise (stdout vide, code de sortie 0).
+
+---
+
+## Politiques intégrées
+
+`src/hooks/builtin-policies.ts` définit les 39 politiques intégrées sous forme d'objets `BuiltinPolicyDefinition` :
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Les politiques acceptant des `params` déclarent un `PolicyParamsSchema` avec les types et valeurs par défaut de chaque paramètre. L'évaluateur de politiques injecte les valeurs résolues dans `ctx.params` avant d'appeler `fn`. Les fonctions de politique lisent `ctx.params` sans vérification de nullité, car les valeurs par défaut sont toujours appliquées en premier.
+
+La correspondance de motifs au sein des politiques utilise des tokens de commande analysés (argv), et non une correspondance de chaînes brutes. Cela empêche tout contournement par injection d'opérateurs shell (par exemple, un motif pour `sudo systemctl status *` ne peut pas être contourné en ajoutant `; rm -rf /` à la commande).
+
+---
+
+## Politiques personnalisées
+
+`src/hooks/custom-hooks-registry.ts` implémente un registre adossé à `globalThis` :
+
+```typescript
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+export const customPolicies = {
+  add(hook: CustomHook): void { ... }
+};
+
+export function getCustomHooks(): CustomHook[] { ... }
+export function clearCustomHooks(): void { ... }  // used in tests
+```
+
+`src/hooks/custom-hooks-loader.ts` charge le fichier de politique de l'utilisateur :
+
+1. Lecture de `customPoliciesPath` depuis la configuration ; ignoré s'il est absent.
+2. Résolution vers un chemin absolu ; vérification de l'existence du fichier.
+3. Réécriture de toutes les importations `from "failproofai"` vers le chemin dist réel, afin que `customPolicies` se résolve vers le même registre `globalThis`.
+4. Réécriture récursive des imports locaux transitifs pour garantir la compatibilité ESM.
+5. Écriture de fichiers `.mjs` temporaires et `import()` du fichier d'entrée.
+6. Appel de `getCustomHooks()` pour récupérer les hooks enregistrés.
+7. Nettoyage de tous les fichiers temporaires dans un bloc `finally`.
+
+En cas d'erreur (fichier introuvable, erreur de syntaxe, échec d'import), l'erreur est consignée dans `~/.failproofai/hook.log` et le chargeur retourne un tableau vide. Les politiques intégrées ne sont pas affectées.
+
+Les politiques personnalisées sont évaluées après toutes les politiques intégrées. Un `deny` d'une politique personnalisée court-circuite quand même les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade).
+
+---
+
+## Journalisation de l'activité
+
+Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL à `~/.failproofai/hook-activity/current.jsonl`, qui est archivée dans `page-<timestamp>-<seq>.jsonl` une fois qu'elle atteint une page :
+
+```json
+{
+  "timestamp": "2026-04-06T12:34:56.789Z",
+  "sessionId": "abc123",
+  "eventType": "PreToolUse",
+  "toolName": "Bash",
+  "policyName": "block-sudo",
+  "decision": "deny",
+  "reason": "sudo command blocked by failproofai",
+  "durationMs": 12
+}
+```
+
+Une ligne par politique ayant rendu une décision autre qu'allow. Les décisions d'autorisation ne sont pas journalisées (afin de limiter la taille du fichier).
+
+---
+
+## Architecture du tableau de bord
+
+Le tableau de bord est une application **Next.js 16** utilisant l'App Router avec les React Server Components et les Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Mise en page racine (thème, télémétrie, navigation)
+  projects/page.tsx           ← Composant serveur : liste tous les projets Claude
+  project/[name]/page.tsx     ← Composant serveur : liste les sessions d'un projet
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Composant serveur : affiche le visualiseur de session
+  policies/page.tsx           ← Composant client : gestion des politiques + journal d'activité
+  actions/
+    get-hooks-config.ts       ← Lecture de la configuration + liste des politiques
+    update-hooks-config.ts    ← Activation/désactivation d'une politique
+    update-policy-params.ts   ← Mise à jour des paramètres d'une politique
+    get-hook-activity.ts      ← Pagination/recherche dans le journal d'activité
+    install-hooks-web.ts      ← Installation/suppression des hooks depuis le navigateur
+  api/
+    download/[project]/[session]/route.ts   ← Export de session CLI (JSONL ou JSON)
+```
+
+**Flux de données :**
+
+- Les composants de page appellent `lib/projects.ts` et `lib/log-entries.ts` pour lire les données de projet et de session directement depuis le système de fichiers (pas de couche API pour les lectures).
+- La page Policies utilise des Server Actions pour toutes les mutations (activation/désactivation, mise à jour des paramètres, installation/suppression).
+- Le visualiseur de session analyse le format de transcript JSONL de Claude et affiche une chronologie des messages et des appels d'outils.
+
+**Décisions de conception clés :**
+
+- Pas de base de données - tout l'état persistant est dans des fichiers plats (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions pour les mutations - pas d'API REST nécessaire pour les opérations CRUD.
+- React Server Components pour les pages de lecture - chargement initial plus rapide, pas de bundle client pour la récupération de données.
+- Composants client uniquement là où l'interactivité est requise (bascules de politiques, recherche dans l'activité, visualiseur de logs).
+
+---
+
+## Organisation des fichiers
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # Routeur CLI (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Pipeline des événements de hook
+│   ├── builtin-policies.ts       # 39 définitions de politiques
+│   ├── policy-evaluator.ts       # Moteur d'exécution des politiques
+│   ├── policy-registry.ts        # Enregistrement et recherche des politiques
+│   ├── policy-types.ts           # Interfaces TypeScript
+│   ├── hooks-config.ts           # Chargement de la configuration multi-portée
+│   ├── custom-hooks-registry.ts  # Registre de hooks adossé à globalThis
+│   ├── custom-hooks-loader.ts    # Chargeur ESM pour les hooks JS utilisateur
+│   ├── manager.ts                # Opérations d'installation / suppression / listage
+│   ├── install-prompt.ts         # Invite interactive de sélection des politiques
+│   ├── hook-logger.ts            # Journalisation vers hook.log
+│   ├── hook-activity-store.ts    # Persistance de l'activité dans hook-activity/
+│   └── llm-client.ts             # Client API LLM (pour les politiques basées sur l'IA)
+├── app/                          # Tableau de bord Next.js (pages + server actions)
+├── lib/                          # Utilitaires partagés
+│   ├── projects.ts               # Énumération des projets Claude depuis le système de fichiers
+│   ├── log-entries.ts            # Analyse du format de transcript JSONL de Claude
+│   ├── paths.ts                  # Résolution des chemins système
+│   └── ...
+├── components/                   # Composants UI React partagés
+├── contexts/                     # Fournisseurs de contexte React (thème, actualisation automatique, télémétrie)
+├── examples/                     # Exemples de fichiers de hooks personnalisés
+└── __tests__/                    # Tests unitaires et E2E
+```