failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,52 @@
+---
+title: "Performance-Metriken"
+description: "Erkenne sofort, wenn deine Modelle, Tools oder Hooks langsamer werden oder Kosten verursachen, und fange Tail-Latency-Spitzen ab, bevor deine Nutzer sie überhaupt bemerken."
+---
+
+
+Erkenne sofort, wenn deine Modelle, Tools oder Hooks langsamer werden oder Kosten verursachen, und fange Tail-Latency-Spitzen ab, bevor deine Nutzer sie überhaupt bemerken. Drei dedizierte Seiten verwandeln rohe Laufzeiten in p50, p95 und p99, die du auf einen Blick ablesen kannst.
+
+![Die Models-Seite mit einer Latency-Heatmap, einem Percentile-Band und modellspezifischen Token-, Kosten- und Kontextfenster-Werten](/agenteye/images/models.png)
+*Die Models-Seite: eine Latency-Heatmap, ein Percentile-Band sowie modellspezifische Token-Zahlen, geschätzte Kosten und die Kontextfenster-Auslastung.*
+
+## Lass Durchschnittswerte nicht mehr deine schlechtesten Läufe verbergen
+
+Eine durchschnittliche Latenzangabe klingt beruhigend – und ist gleichzeitig nutzlos: Sie glättet genau jenen einen Aufruf unter fünfzig, der ins Stocken gerät und deinen Bereitschaftsdienst um 2 Uhr nachts weckt. Die Seiten Models, Tools und Hooks machen das nicht mit. Alle drei haben denselben Aufbau, den du nur einmal lernen musst:
+
+- Ein **24-Bin-Sparkline** für den Trend auf einen Blick: Wird es schlechter?
+- Ein **Vitals-Streifen** mit p50, p95 und p99 Latenz, damit der typische Lauf und der Ausreißer nebeneinander stehen.
+- Eine **Latency-Heatmap** – 24 Zeitabschnitte gegen Latenz-Buckets –, die zeigt, *wann* sich die langsamen Aufrufe gehäuft haben.
+- Ein **Percentile-Band**: eine p50-Linie mit schraffierten Bändern für p25–p75 und p10–p90 sowie p99-Punkte, sodass die Streuung sichtbar bleibt, anstatt weggemittelt zu werden.
+
+Ein gemeinsames Hover-Fadenkreuz verknüpft Heatmap und Band zeitlich miteinander, sodass ein Tail-Spike in beiden Ansichten an derselben Stelle erscheint, statt hinter einer einzigen Mittellinie zu verschwinden. Alle drei Seiten findest du im Bereich **observe** deines Dashboards – gefiltert nach Organisation und einschränkbar nach Datumsbereich, Umgebung, Agent und Session.
+
+## Models: sieh genau, was jedes Modell dich kostet
+
+Die Models-Seite (oben abgebildet) beantwortet die zwei Fragen, die eine Rechnung immer aufwirft: Welches Modell, und wie viel? Zusätzlich zur gemeinsamen Latenzansicht zeigt sie **modellspezifischen Token-Verbrauch**, **geschätzte Kosten** und die **Kontextfenster-Auslastung** – damit unkontrolliertes Prompt-Wachstum und eine bevorstehende Kompaktierung sichtbar werden, bevor sie dich überraschen.
+
+Failproof AI Observability erkennt gängige Modell-IDs automatisch. Falls ein Fenster falsch aussieht oder du ein eigenes privates Modell betreibst, korrigiere es oder füge eines unter **Settings** bei **model context windows** hinzu – die Auslastungsanzeigen passen sich entsprechend an.
+
+## Tools: unterscheide langsam von defekt
+
+Ein Tool-Aufruf kann langsam sein oder stillschweigend fehlschlagen – und du möchtest das in Sekunden wissen, nicht erst nach stundenlangem Log-Wühlen.
+
+![Die Tools-Seite mit der gemeinsamen Latency-Heatmap und dem Percentile-Band neben einer Erfolgs- und Fehleraufschlüsselung sowie einem Tool-Verteilungsbalken](/agenteye/images/tools.png)
+*Die Tools-Seite: dieselbe Heatmap und dasselbe Percentile-Band, ergänzt um eine Erfolgs- und Fehleraufschlüsselung sowie einen Tool-Verteilungsbalken.*
+
+Neben der gemeinsamen Latenzansicht fügt die Tools-Seite eine **Erfolgs- und Fehleraufschlüsselung** sowie einen **Tool-Verteilungsbalken** hinzu, sodass du auf einen Blick siehst, welche Tools du am häufigsten verwendest und welche dein Fehlerbudget auffressen.
+
+## Hooks: den genauen Hook und Trigger ermitteln
+
+Wenn ein Lifecycle-Hook einen Lauf verlangsamt, kannst du mit der Aussage „Hooks sind langsam" nichts anfangen. Die Hooks-Seite führt dich direkt zu dem einen, der das Problem verursacht.
+
+![Die Hooks-Seite mit nach Hook-Name und Trigger-Event aufgeschlüsselter Latenz über der gemeinsamen Heatmap und dem Percentile-Band](/agenteye/images/hooks.png)
+*Die Hooks-Seite: Latenz aufgeschlüsselt nach Hook-Name und Trigger-Event.*
+
+Über derselben Latency-Heatmap und demselben Percentile-Band schlüsselt die Hooks-Seite die Aktivität nach **Hook-Name** und **Trigger-Event** auf, sodass du direkt bei dem einen Hook und dem einen Event landest, der Aufmerksamkeit erfordert.
+
+## Verwandte Seiten
+
+- [Event-Stream](/de/agenteye/event-stream): der Live-Feed aller Events, farblich kodiert.
+- [Sessions](/de/agenteye/sessions): Events zu einer Zeile pro Lauf zusammenfassen und den Ausführungsgraphen öffnen.
+- [Fehlerverfolgung](/de/agenteye/error-tracking): eine zentrale Triage-Oberfläche für alles, was das Dashboard rot einfärbt.
+- [Dashboards](/de/agenteye/dashboards): Übersichtsansichten über deine gesamte Flotte.

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

@@ -0,0 +1,332 @@
+---
+title: Architektur
+description: "Wie der Hook-Handler, das Laden der Konfiguration und die Policy-Auswertung intern funktionieren"
+icon: sitemap
+---
+
+Dieses Dokument erläutert, wie failproofai intern funktioniert: wie das Hook-System Agent-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Policies ausgewertet werden und wie das Dashboard die Aktivitäten des Agenten überwacht.
+
+---
+
+## Überblick
+
+failproofai besteht aus zwei unabhängigen Subsystemen:
+
+1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agent-Tool-Aufruf aufruft. Er wertet Policies aus und gibt eine Entscheidung zurück.
+2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agent-Sitzungen und Verwaltung von Policies.
+
+Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen jedoch als separate Prozesse und kommunizieren ausschließlich über das Dateisystem.
+
+---
+
+## Hook-Handler
+
+### Integration mit Claude Code
+
+Wenn Sie `failproofai policies --install` ausführen, werden folgende Einträge in `~/.claude/settings.json` geschrieben:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code ruft `failproofai --hook PreToolUse` dann vor jedem Tool-Aufruf als Subprozess auf und übergibt dabei einen JSON-Payload über stdin.
+
+### Payload-Format
+
+```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" }
+}
+```
+
+Bei `PostToolUse`-Ereignissen enthält der Payload zusätzlich `tool_result` mit der Ausgabe des Tools.
+
+Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit überschreiten, werden verworfen, und alle Policies erlauben implizit.
+
+### Antwortformat
+
+**Ablehnen (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Ablehnen (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Anweisen (beliebiges Ereignis außer Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Stop-Ereignis anweisen:**
+- Exit-Code: `2`
+- Grund wird in stderr geschrieben (nicht stdout)
+
+**Erlauben:**
+- Exit-Code: `0`
+- Leerer stdout
+
+**Erlauben mit Nachricht:**
+
+`allow(message)` ermöglicht es einer Policy, informativen Kontext an Claude zurückzusenden, auch wenn der Vorgang erlaubt ist. Der Hook-Handler schreibt folgenden JSON-Code nach **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie die Ablehnen- und Anweisen-Antworten oben):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Exit-Code: `0` (Vorgang ist erlaubt)
+- Wenn mehrere Policies `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzelnen `additionalContext`-String zusammengeführt
+- Wenn keine Policy eine Nachricht liefert, ist stdout leer (wie zuvor)
+
+### Verarbeitungspipeline
+
+`src/hooks/handler.ts` implementiert die vollständige Pipeline:
+
+```text
+stdin JSON
+  → Payload parsen (max. 1 MB)
+  → Sitzungsmetadaten extrahieren (session_id, cwd, tool_name, tool_input, etc.)
+  → readMergedHooksConfig(cwd)    ← Projekt-, lokale und globale Konfiguration zusammenführen
+  → aktivierte eingebaute Policies mit aufgelösten Parametern registrieren
+  → benutzerdefinierte Policies aus customPoliciesPath laden (falls angegeben)
+  → benutzerdefinierte Policies in die Policy-Registry registrieren
+  → alle Policies auswerten (zuerst eingebaute, dann benutzerdefinierte)
+      → erster deny-Bescheid schließt die Verarbeitung kurz
+      → instruct-Entscheidungen werden gesammelt
+      → allow-Nachrichten werden gesammelt
+  → JSON-Entscheidung nach stdout schreiben
+  → Ereignis nach ~/.failproofai/hook-activity/current.jsonl persistieren
+  → beenden
+```
+
+Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 ms ab.
+
+---
+
+## Konfigurationsladung
+
+`src/hooks/hooks-config.ts` implementiert das Laden von Konfigurationen mit drei Geltungsbereichen.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← Projekt  (höchste Priorität)
+[2] {cwd}/.failproofai/policies-config.local.json  ← lokal
+[3] ~/.failproofai/policies-config.json             ← global   (niedrigste Priorität)
+```
+
+Zusammenführungslogik:
+- `enabledPolicies` – deduplizierte Vereinigung aus allen drei Dateien
+- `policyParams` – pro Policy-Schlüssel gewinnt die erste Datei, die ihn definiert, vollständig
+- `customPoliciesPath` – die erste Datei, die ihn definiert, gewinnt
+- `llm` – die erste Datei, die ihn definiert, gewinnt
+
+Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es nicht mit einem Projekt-cwd aufgerufen wird.
+
+---
+
+## Policy-Auswertung
+
+`src/hooks/policy-evaluator.ts` führt Policies der Reihe nach aus.
+
+Für jede Policy:
+
+1. Das `params`-Schema der Policy nachschlagen (falls vorhanden).
+2. `policyParams[policy.name]` aus der zusammengeführten Konfiguration lesen.
+3. Vom Benutzer bereitgestellte Werte über die Schema-Standardwerte zusammenführen, um `ctx.params` zu erzeugen.
+4. `policy.fn(ctx)` mit dem aufgelösten Kontext aufrufen.
+5. Ist das Ergebnis `deny`, sofort stoppen und diese Entscheidung zurückgeben.
+6. Ist das Ergebnis `instruct`, die Nachricht sammeln und fortfahren.
+7. Ist das Ergebnis `allow`, mit der nächsten Policy fortfahren.
+
+Nachdem alle Policies ausgeführt wurden:
+- Falls ein `deny` zurückgegeben wurde, die Ablehnen-Antwort ausgeben.
+- Falls `instruct`-Rückgaben gesammelt wurden, eine einzelne Anweisen-Antwort mit allen zusammengeführten Nachrichten ausgeben.
+- Andernfalls eine Erlauben-Antwort ausgeben (leerer stdout, Exit 0).
+
+---
+
+## Eingebaute Policies
+
+`src/hooks/builtin-policies.ts` definiert alle 39 eingebauten Policies als `BuiltinPolicyDefinition`-Objekte:
+
+```typescript
+interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: (ctx: PolicyContext) => PolicyResult;
+  match: {
+    events: HookEventType[];
+    tools?: string[];
+  };
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+```
+
+Policies, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Policy-Evaluator injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. Policy-Funktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden.
+
+Das Pattern-Matching innerhalb von Policies verwendet geparste Befehlstoken (argv) und kein einfaches String-Matching. Dies verhindert Umgehungsversuche durch Shell-Operator-Injektion (z. B. kann ein Pattern für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden).
+
+---
+
+## Benutzerdefinierte Policies
+
+`src/hooks/custom-hooks-registry.ts` implementiert eine `globalThis`-basierte Registry:
+
+```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` lädt die Policy-Datei des Benutzers:
+
+1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, falls nicht vorhanden.
+2. Zu absolutem Pfad auflösen; prüfen, ob die Datei existiert.
+3. Alle `from "failproofai"`-Importe zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` auf dieselbe `globalThis`-Registry verweist.
+4. Transitive lokale Importe rekursiv umschreiben, um ESM-Kompatibilität sicherzustellen.
+5. Temporäre `.mjs`-Dateien schreiben und die Einstiegsdatei per `import()` laden.
+6. `getCustomHooks()` aufrufen, um registrierte Hooks abzurufen.
+7. Alle temporären Dateien in einem `finally`-Block bereinigen.
+
+Bei einem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert, und der Loader gibt ein leeres Array zurück. Eingebaute Policies sind davon nicht betroffen.
+
+Benutzerdefinierte Policies werden nach allen eingebauten Policies ausgewertet. Ein `deny` einer benutzerdefinierten Policy schließt weitere benutzerdefinierte Policies ebenfalls kurz (alle eingebauten Policies wurden zu diesem Zeitpunkt jedoch bereits ausgeführt).
+
+---
+
+## Aktivitätsprotokollierung
+
+Nach jedem Hook-Ereignis hängt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity/current.jsonl` an, die in `page-<timestamp>-<seq>.jsonl` rotiert wird, sobald eine Seite erreicht ist:
+
+```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
+}
+```
+
+Eine Zeile pro Policy, die eine Nicht-Erlauben-Entscheidung getroffen hat. Erlauben-Entscheidungen werden nicht protokolliert (um die Datei klein zu halten).
+
+---
+
+## Dashboard-Architektur
+
+Das Dashboard ist eine **Next.js 16**-Anwendung, die den App Router mit React Server Components und Server Actions verwendet.
+
+```text
+app/
+  layout.tsx                  ← Root-Layout (Theme, Telemetrie, Navigation)
+  projects/page.tsx           ← Server Component: alle Claude-Projekte auflisten
+  project/[name]/page.tsx     ← Server Component: Sitzungen in einem Projekt auflisten
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Server Component: Sitzungs-Viewer rendern
+  policies/page.tsx           ← Client Component: Policy-Verwaltung + Aktivitätslog
+  actions/
+    get-hooks-config.ts       ← Konfiguration + Policy-Liste lesen
+    update-hooks-config.ts    ← Policy ein-/ausschalten
+    update-policy-params.ts   ← Policy-Parameter aktualisieren
+    get-hook-activity.ts      ← Aktivitätslog paginieren/durchsuchen
+    install-hooks-web.ts      ← Hooks über den Browser installieren/entfernen
+  api/
+    download/[project]/[session]/route.ts   ← Export einzelner CLI-Sitzungen (JSONL oder JSON)
+```
+
+**Datenfluss:**
+
+- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt-/Sitzungsdaten direkt aus dem Dateisystem zu lesen (keine API-Schicht für Lesevorgänge).
+- Die Policies-Seite verwendet Server Actions für alle Mutationen (Umschalten, Parameter-Aktualisierung, Installieren/Entfernen).
+- Der Sitzungs-Viewer parst das JSONL-Transkriptformat von Claude und rendert eine Zeitleiste mit Nachrichten und Tool-Aufrufen.
+
+**Wesentliche Designentscheidungen:**
+
+- Keine Datenbank – alle persistenten Zustände liegen in einfachen Dateien (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions für Mutationen – keine REST-API für CRUD-Operationen erforderlich.
+- React Server Components für Leseseiten – schnelleres initiales Laden, kein Client-Bundle für das Abrufen von Daten.
+- Client Components nur dort, wo Interaktivität erforderlich ist (Policy-Umschalter, Aktivitätssuche, Log-Viewer).
+
+---
+
+## Dateistruktur
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI-Router (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Hook-Ereignis-Pipeline
+│   ├── builtin-policies.ts       # 39 Policy-Definitionen
+│   ├── policy-evaluator.ts       # Policy-Ausführungs-Engine
+│   ├── policy-registry.ts        # Policy-Registrierung und -Suche
+│   ├── policy-types.ts           # TypeScript-Interfaces
+│   ├── hooks-config.ts           # Konfigurationsladung mit mehreren Geltungsbereichen
+│   ├── custom-hooks-registry.ts  # globalThis-basierte Hook-Registry
+│   ├── custom-hooks-loader.ts    # ESM-Loader für benutzerdefinierte JS-Hooks
+│   ├── manager.ts                # Installieren / Entfernen / Auflisten von Operationen
+│   ├── install-prompt.ts         # Interaktive Policy-Auswahlmaske
+│   ├── hook-logger.ts            # Protokollierung in hook.log
+│   ├── hook-activity-store.ts    # Aktivität in hook-activity/ persistieren
+│   └── llm-client.ts             # LLM-API-Client (für KI-gestützte Policies)
+├── app/                          # Next.js-Dashboard (Seiten + Server Actions)
+├── lib/                          # Gemeinsam genutzte Hilfsprogramme
+│   ├── projects.ts               # Claude-Projekte aus dem Dateisystem auflisten
+│   ├── log-entries.ts            # JSONL-Transkriptformat von Claude parsen
+│   ├── paths.ts                  # Systempfade auflösen
+│   └── ...
+├── components/                   # Gemeinsam genutzte React-UI-Komponenten
+├── contexts/                     # React-Context-Provider (Theme, Auto-Refresh, Telemetrie)
+├── examples/                     # Beispieldateien für benutzerdefinierte Hooks
+└── __tests__/                    # Unit- und E2E-Tests
+```