failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,52 @@
+---
+title: "Metriche di Prestazione"
+description: "Vedi l'istante in cui i tuoi modelli, strumenti o hook rallentano o fanno lievitare i costi, e intercetta un picco di latenza coda prima che i tuoi utenti lo avvertano."
+---
+
+
+Vedi l'istante in cui i tuoi modelli, strumenti o hook rallentano o fanno lievitare i costi, e intercetta un picco di latenza coda prima che i tuoi utenti lo avvertano. Tre pagine dedicate trasformano i tempi grezzi in p50, p95 e p99 leggibili a colpo d'occhio.
+
+![La pagina Models che mostra una mappa di calore della latenza, una banda percentile e figure di token, costo e finestra di contesto per modello](/agenteye/images/models.png)
+*La pagina Models: una mappa di calore della latenza, una banda percentile e token per modello, costo stimato e riempimento della finestra di contesto.*
+
+## Smetti di lasciare che le medie nascondano le tue peggiori esecuzioni
+
+Un numero di latenza media è rassicurante e inutile: nasconde quella chiamata su cinquanta che si blocca e ti sveglia di soppiatto alle 2 di mattina. Le pagine Models, Tools e Hooks rifiutano di farlo. Ognuna condivide la stessa struttura, così la impari una volta:
+
+- Una **sparkline a 24 bin** per il trend a colpo d'occhio: sta peggiorando?
+- Una **striscia di vitali** con latenza p50, p95 e p99, così l'esecuzione tipica e la coda stanno fianco a fianco.
+- Una **mappa di calore della latenza**, 24 bin temporali per bucket di latenza, che mostra *quando* le chiamate lente si sono raggruppate.
+- Una **banda percentile**: una linea p50 con nastri ombreggiati da p25 a p75 e da p10 a p90 e punti p99, così la distribuzione rimane visibile invece di essere mediata.
+
+Un mirino di hover condiviso collega la mappa di calore e la banda, così un picco di coda si allinea nel tempo su entrambe invece di nascondersi dietro una singola linea media. Trova tutte e tre le pagine nella sezione **observe** del tuo dashboard, ognuna con ambito alla tua organizzazione e filtrabile per intervallo di date, ambiente, agente e sessione.
+
+## Models: vedi esattamente quanto ogni modello ti costa
+
+La pagina Models (mostrata in alto) risponde alle due domande che una fattura pone sempre: quale modello e quanto costa. In aggiunta alla vista di latenza condivisa, aggiunge **consumo di token per modello**, **costo stimato** e **riempimento della finestra di contesto**, così la crescita della prompt incontrollata e una compattazione imminente sono visibili prima di sorprenderti.
+
+Failproof AI Observability riconosce automaticamente gli ID dei modelli comuni. Se una finestra sembra scorretta o esegui un modello privato tuo, correggilo o aggiungine uno in **Settings**, in **model context windows**, e le letture del riempimento seguiranno.
+
+## Tools: distingui il lento dal rotto
+
+Una chiamata di strumento può essere lenta, oppure può stare fallendo in silenzio, e vuoi sapere quale sia in secondi, non dopo aver scavato nei log.
+
+![La pagina Tools che mostra la mappa di calore della latenza condivisa e la banda percentile accanto a un dettaglio di successo e fallimento e una barra di distribuzione degli strumenti](/agenteye/images/tools.png)
+*La pagina Tools: la stessa mappa di calore e banda percentile, più un dettaglio di successo e fallimento e una barra di distribuzione degli strumenti.*
+
+Accanto alla vista di latenza condivisa, la pagina Tools aggiunge un **dettaglio di successo e fallimento** e una **barra di distribuzione degli strumenti**, così vedi a colpo d'occhio quali strumenti usi di più e quali stanno consumando il tuo budget di errori.
+
+## Hooks: individua esattamente l'hook e il trigger
+
+Quando un hook del ciclo di vita fa rallentare un'esecuzione, "gli hook sono lenti" non è qualcosa su cui puoi agire. La pagina Hooks ti porta a quello che conta.
+
+![La pagina Hooks che mostra la latenza suddivisa per nome dell'hook e evento trigger sulla mappa di calore e banda percentile condivise](/agenteye/images/hooks.png)
+*La pagina Hooks: latenza suddivisa per nome dell'hook e evento trigger.*
+
+Sulla stessa mappa di calore della latenza e banda percentile, la pagina Hooks suddivide l'attività per **nome dell'hook** e **evento trigger**, così arrivi all'hook singolo e all'evento singolo che hanno bisogno di attenzione.
+
+## Correlati
+
+- [Event stream](/it/agenteye/event-stream): il percorso codificato a colori live di ogni evento.
+- [Sessions](/it/agenteye/sessions): raggruppa gli eventi in una riga per esecuzione e apri il suo grafico di esecuzione.
+- [Error tracking](/it/agenteye/error-tracking): una superficie di triage per tutto quello che il dashboard dipinge di rosso.
+- [Dashboards](/it/agenteye/dashboards): viste riepilogative sulla tua flotta.

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

@@ -0,0 +1,333 @@
+---
+---
+title: Architettura
+description: "Come il gestore hook, il caricamento della configurazione e la valutazione delle policy funzionano internamente"
+icon: sitemap
+---
+
+Questo documento spiega come failproofai funziona internamente: come il sistema di hook intercetta le chiamate ai tool dell'agente, come viene caricata e unita la configurazione, come vengono valutate le policy e come il dashboard monitora l'attività dell'agente.
+
+---
+
+## Panoramica
+
+failproofai ha due sottosistemi indipendenti:
+
+1. **Hook handler** - Un veloce sottoprocesso CLI che Claude Code invoca ad ogni chiamata di tool dell'agente. Valuta le policy e restituisce una decisione.
+2. **Agent Monitor (Dashboard)** - Un'applicazione web Next.js per monitorare le sessioni dell'agente e gestire le policy.
+
+Entrambi i sottosistemi condividono i file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem.
+
+---
+
+## Hook handler
+
+### Integrazione con Claude Code
+
+Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code invoca quindi `failproofai --hook PreToolUse` come sottoprocesso prima di ogni chiamata di tool, passando un payload JSON su stdin.
+
+### Formato del payload
+
+```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" }
+}
+```
+
+Per gli eventi `PostToolUse`, il payload contiene anche `tool_result` con l'output del tool.
+
+Il gestore applica un limite di 1 MB su stdin. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente.
+
+### Formato della risposta
+
+**Deny (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Deny (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Instruct (qualsiasi evento tranne Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Evento Stop instruct:**
+- Exit code: `2`
+- Motivo scritto su stderr (non stdout)
+
+**Allow:**
+- Exit code: `0`
+- stdout vuoto
+
+**Allow con messaggio:**
+
+`allow(message)` consente a una policy di inviare un contesto informativo indietro a Claude anche quando l'operazione è consentita. Il gestore hook scrive il seguente JSON su **stdout** (non un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct sopra):
+
+```json
+// Scritto su stdout dal processo gestore hook
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Exit code: `0` (operazione consentita)
+- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con interruzioni di riga in una singola stringa `additionalContext`
+- Se nessuna policy fornisce un messaggio, stdout è vuoto (come prima)
+
+### Pipeline di elaborazione
+
+`src/hooks/handler.ts` implementa la pipeline completa:
+
+```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'intero processo viene eseguito in meno di 100ms per i payload tipici senza chiamate LLM.
+
+---
+
+## Caricamento della configurazione
+
+`src/hooks/hooks-config.ts` implementa il caricamento della configurazione a tre livelli.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
+```
+
+Logica di unione:
+- `enabledPolicies` - unione deduplicated tra i tre file
+- `policyParams` - per ogni policy, il primo file che la definisce vince interamente
+- `customPoliciesPath` - il primo file che la definisce vince
+- `llm` - il primo file che la definisce vince
+
+Il dashboard web utilizza `readHooksConfig()` (solo globale) per la lettura e la scrittura, poiché non viene invocato con un cwd di progetto.
+
+---
+
+## Valutazione delle policy
+
+`src/hooks/policy-evaluator.ts` esegue le policy in ordine.
+
+Per ogni policy:
+
+1. Cerca lo schema `params` della policy (se ne ha uno).
+2. Legge `policyParams[policy.name]` dalla configurazione unita.
+3. Unisce i valori forniti dall'utente su i valori predefiniti dello schema per produrre `ctx.params`.
+4. Chiama `policy.fn(ctx)` con il contesto risolto.
+5. Se il risultato è `deny`, si ferma immediatamente e restituisce quella decisione.
+6. Se il risultato è `instruct`, accumula il messaggio e continua.
+7. Se il risultato è `allow`, continua alla policy successiva.
+
+Dopo l'esecuzione di tutte le policy:
+- Se è stato restituito qualsiasi `deny`, emette la risposta deny.
+- Se sono stati raccolti risultati `instruct`, emette una singola risposta instruct con tutti i messaggi uniti.
+- Altrimenti, emette una risposta allow (stdout vuoto, exit 0).
+
+---
+
+## Policy integrate
+
+`src/hooks/builtin-policies.ts` definisce tutte le 39 policy integrate come oggetti `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;
+}
+```
+
+Le policy che accettano `params` dichiarano uno `PolicyParamsSchema` con tipi e valori predefiniti per ogni parametro. L'evaluatore di policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni di policy leggono `ctx.params` senza protezione null perché i valori predefiniti vengono sempre applicati per primi.
+
+Il pattern matching all'interno delle policy utilizza token di comando analizzati (argv), non corrispondenze di stringhe grezze. Questo previene i bypass tramite iniezione di operatori shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando).
+
+---
+
+## Policy personalizzate
+
+`src/hooks/custom-hooks-registry.ts` implementa un registro supportato da `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` carica il file di policy dell'utente:
+
+1. Legge `customPoliciesPath` dalla configurazione; salta se assente.
+2. Risolve al percorso assoluto; controlla che il file esista.
+3. Riscrive tutti gli import `from "failproofai"` al percorso dist effettivo così `customPolicies` si risolve nello stesso registro `globalThis`.
+4. Riscrive ricorsivamente gli import locali transitivi per garantire la compatibilità ESM.
+5. Scrive file `.mjs` temporanei e `import()` il file di ingresso.
+6. Chiama `getCustomHooks()` per recuperare i ganci registrati.
+7. Pulisce tutti i file temporanei in un blocco `finally`.
+
+Su qualsiasi errore (file non trovato, errore di sintassi, fallimento dell'import), l'errore viene registrato in `~/.failproofai/hook.log` e il caricatore restituisce un array vuoto. Le policy integrate non sono interessate.
+
+Le policy personalizzate vengono valutate dopo tutte le policy integrate. Un `deny` di policy personalizzata ancora interrompe ulteriori policy personalizzate (ma tutte le integrate sono già state eseguite a quel punto).
+
+---
+
+## Logging dell'attività
+
+Dopo ogni evento hook, il gestore aggiunge una riga JSONL a `~/.failproofai/hook-activity/current.jsonl`, che ruota in `page-<timestamp>-<seq>.jsonl` una volta raggiunta una pagina:
+
+```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
+}
+```
+
+Una riga per ogni policy che ha preso una decisione non-allow. Le decisioni allow non vengono registrate (per mantenere il file piccolo).
+
+---
+
+## Architettura del dashboard
+
+Il dashboard è un'applicazione **Next.js 16** che utilizza l'App Router con React Server Components e Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Root layout (theme, telemetry, nav)
+  projects/page.tsx           ← Server component: list all Claude projects
+  project/[name]/page.tsx     ← Server component: list sessions in a project
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Server component: render session viewer
+  policies/page.tsx           ← Client component: policy management + activity log
+  actions/
+    get-hooks-config.ts       ← Read config + policy list
+    update-hooks-config.ts    ← Toggle policy on/off
+    update-policy-params.ts   ← Update policy parameters
+    get-hook-activity.ts      ← Paginate/search activity log
+    install-hooks-web.ts      ← Install/remove hooks from the browser
+  api/
+    download/[project]/[session]/route.ts   ← Per-CLI session export (JSONL or JSON)
+```
+
+**Flusso dati:**
+
+- I componenti pagina chiamano `lib/projects.ts` e `lib/log-entries.ts` per leggere i dati di progetto/sessione direttamente dal filesystem (nessun livello API per le letture).
+- La pagina Policies utilizza Server Actions per tutte le mutazioni (attiva/disattiva, aggiornamento parametri, installa/rimuovi).
+- Il visualizzatore di sessione analizza il formato di trascrizione JSONL di Claude e renderizza una timeline di messaggi e chiamate di tool.
+
+**Decisioni di design chiave:**
+
+- Nessun database - tutto lo stato persistente è in file semplici (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions per le mutazioni - nessuna API REST necessaria per le operazioni CRUD.
+- React Server Components per le pagine di lettura - caricamento iniziale più veloce, nessun bundle client per il recupero dei dati.
+- Componenti client solo dove è necessaria l'interattività (attivazioni/disattivazioni policy, ricerca attività, visualizzatore log).
+
+---
+
+## Layout dei file
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Hook event pipeline
+│   ├── builtin-policies.ts       # 39 policy definitions
+│   ├── policy-evaluator.ts       # Policy execution engine
+│   ├── policy-registry.ts        # Policy registration and lookup
+│   ├── policy-types.ts           # TypeScript interfaces
+│   ├── hooks-config.ts           # Multi-scope config loading
+│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
+│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
+│   ├── manager.ts                # install / remove / list operations
+│   ├── install-prompt.ts         # Interactive policy selection prompt
+│   ├── hook-logger.ts            # Logging to hook.log
+│   ├── hook-activity-store.ts    # Persist activity to hook-activity/
+│   └── llm-client.ts             # LLM API client (for AI-powered policies)
+├── app/                          # Next.js dashboard (pages + server actions)
+├── lib/                          # Shared utilities
+│   ├── projects.ts               # Enumerate Claude projects from filesystem
+│   ├── log-entries.ts            # Parse Claude transcript JSONL format
+│   ├── paths.ts                  # Resolve system paths
+│   └── ...
+├── components/                   # Shared React UI components
+├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
+├── examples/                     # Example custom hook files
+└── __tests__/                    # Unit and E2E tests
+```