failproofai 1.0.1-beta.1 → 1.0.1

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

@@ -0,0 +1,52 @@
+---
+title: "Métricas de rendimiento"
+description: "Detecta al instante cuándo tus modelos, herramientas o hooks ralentizan el sistema o disparan la factura, y anticipa un pico de latencia de cola antes de que tus usuarios lo noten."
+---
+
+
+Detecta al instante cuándo tus modelos, herramientas o hooks ralentizan el sistema o disparan la factura, y anticipa un pico de latencia de cola antes de que tus usuarios lo noten. Tres páginas dedicadas convierten los tiempos brutos en p50, p95 y p99 que puedes leer de un vistazo.
+
+![La página de Modelos con un mapa de calor de latencia, una banda de percentiles y datos de tokens, coste y ventana de contexto por modelo](/agenteye/images/models.png)
+*La página de Modelos: un mapa de calor de latencia, una banda de percentiles y, por modelo, tokens, coste estimado y ocupación de la ventana de contexto.*
+
+## Deja de permitir que los promedios oculten tus peores ejecuciones
+
+Un número de latencia promedio es tranquilizador e inútil: suaviza la llamada de cada cincuenta que se atasca y despierta a tu equipo de guardia a las 2 a.m. Las páginas de Modelos, Herramientas y Hooks se niegan a hacer eso. Todas comparten la misma estructura, así que la aprendes una sola vez:
+
+- Un **sparkline de 24 intervalos** para ver la tendencia de un vistazo: ¿está empeorando?
+- Una **tira de estadísticas vitales** con latencia p50, p95 y p99, de modo que la ejecución típica y la de cola se muestran una al lado de la otra.
+- Un **mapa de calor de latencia**, con 24 intervalos de tiempo por rangos de latencia, que muestra *cuándo* se agruparon las llamadas lentas.
+- Una **banda de percentiles**: una línea p50 con cintas sombreadas de p25 a p75 y de p10 a p90, más puntos p99, para que la dispersión sea visible en lugar de quedar diluida en un promedio.
+
+Un crosshair de hover compartido vincula el mapa de calor y la banda, de modo que un pico de cola se alinea temporalmente en ambos en lugar de ocultarse detrás de una única línea media. Encontrarás las tres páginas en la sección **observe** de tu dashboard, cada una con alcance a tu organización y filtrable por rango de fechas, entorno, agente y sesión.
+
+## Modelos: ve exactamente lo que cada modelo te cuesta
+
+La página de Modelos (mostrada arriba) responde las dos preguntas que siempre plantea una factura: qué modelo y cuánto. Además de la vista de latencia compartida, añade el **consumo de tokens por modelo**, el **coste estimado** y la **ocupación de la ventana de contexto**, de modo que el crecimiento desbocado de los prompts y una compactación inminente son visibles antes de que te sorprendan.
+
+Failproof AI Observability reconoce los IDs de modelos más comunes automáticamente. Si una ventana aparece incorrecta o ejecutas un modelo privado propio, corrígelo o añade uno en **Settings**, en **model context windows**, y las lecturas de ocupación se actualizarán en consecuencia.
+
+## Herramientas: distingue lo lento de lo roto
+
+Una llamada a una herramienta puede ser lenta o puede estar fallando silenciosamente, y quieres saberlo en segundos, no después de revisar logs.
+
+![La página de Herramientas con el mapa de calor de latencia y la banda de percentiles compartidos junto a un desglose de éxitos y fallos y una barra de distribución de herramientas](/agenteye/images/tools.png)
+*La página de Herramientas: el mismo mapa de calor y banda de percentiles, más un desglose de éxitos y fallos y una barra de distribución de herramientas.*
+
+Junto a la vista de latencia compartida, la página de Herramientas añade un **desglose de éxitos y fallos** y una **barra de distribución de herramientas**, para que veas de un vistazo qué herramientas usas más y cuáles están consumiendo tu presupuesto de errores.
+
+## Hooks: identifica el hook y el disparador exactos
+
+Cuando un hook de ciclo de vida ralentiza una ejecución, "los hooks son lentos" no es algo sobre lo que puedas actuar. La página de Hooks te lleva directamente al que importa.
+
+![La página de Hooks con la latencia desglosada por nombre de hook y evento disparador sobre el mapa de calor y la banda de percentiles compartidos](/agenteye/images/hooks.png)
+*La página de Hooks: latencia desglosada por nombre de hook y evento disparador.*
+
+Sobre el mismo mapa de calor de latencia y banda de percentiles, la página de Hooks desglosa la actividad por **nombre de hook** y **evento disparador**, para que llegues al hook concreto y al evento concreto que necesitan atención.
+
+## Relacionado
+
+- [Flujo de eventos](/es/agenteye/event-stream): el rastro en vivo con código de colores de cada evento.
+- [Sesiones](/es/agenteye/sessions): agrupa los eventos en una fila por ejecución y abre su grafo de ejecución.
+- [Seguimiento de errores](/es/agenteye/error-tracking): una única superficie de triaje para todo lo que el dashboard marca en rojo.
+- [Dashboards](/es/agenteye/dashboards): vistas agregadas de toda tu flota.

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

@@ -0,0 +1,332 @@
+---
+title: Arquitectura
+description: "Cómo funcionan internamente el manejador de hooks, la carga de configuración y la evaluación de políticas"
+icon: sitemap
+---
+
+Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y combina la configuración, cómo se evalúan las políticas y cómo el panel de control monitorea la actividad del agente.
+
+---
+
+## Descripción general
+
+failproofai tiene dos subsistemas independientes:
+
+1. **Manejador de hooks** - Un subproceso CLI rápido que Claude Code invoca en cada llamada a una herramienta del agente. Evalúa las políticas y devuelve una decisión.
+2. **Monitor de agentes (Panel de control)** - Una aplicación web Next.js para monitorear sesiones del agente y gestionar políticas.
+
+Ambos subsistemas comparten archivos de configuración en `~/.failproofai/` y en el directorio `.failproofai/` del proyecto, pero se ejecutan como procesos separados y se comunican únicamente a través del sistema de archivos.
+
+---
+
+## Manejador de hooks
+
+### Integración con Claude Code
+
+Cuando ejecutas `failproofai policies --install`, escribe entradas como esta en `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes de cada llamada a una herramienta, enviando un payload JSON por 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" }
+}
+```
+
+Para eventos `PostToolUse`, el payload también contiene `tool_result` con la salida de la herramienta.
+
+El manejador aplica un límite de 1 MB en stdin. Los payloads que superen este límite se descartan y todas las políticas permiten implícitamente.
+
+### Formato de respuesta
+
+**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 (cualquier evento excepto Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Instruct en evento Stop:**
+- Código de salida: `2`
+- El motivo se escribe en stderr (no en stdout)
+
+**Allow:**
+- Código de salida: `0`
+- stdout vacío
+
+**Allow con mensaje:**
+
+`allow(message)` permite que una política envíe contexto informativo de vuelta a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en **stdout** (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas deny e instruct anteriores):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Código de salida: `0` (la operación está permitida)
+- Cuando varias políticas devuelven `allow` con mensaje, sus mensajes se unen con saltos de línea en una sola cadena `additionalContext`
+- Si ninguna política proporciona un mensaje, stdout está vacío (igual que antes)
+
+### Pipeline de procesamiento
+
+`src/hooks/handler.ts` implementa el pipeline completo:
+
+```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
+```
+
+Todo el proceso se ejecuta en menos de 100ms para payloads típicos sin llamadas a LLM.
+
+---
+
+## Carga de configuración
+
+`src/hooks/hooks-config.ts` implementa la carga de configuración en tres ámbitos.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← proyecto  (mayor prioridad)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global   (menor prioridad)
+```
+
+Lógica de combinación:
+- `enabledPolicies` - unión deduplicada de los tres archivos
+- `policyParams` - por clave de política, gana íntegramente el primer archivo que la defina
+- `customPoliciesPath` - gana el primer archivo que lo defina
+- `llm` - gana el primer archivo que lo defina
+
+El panel de control web usa `readHooksConfig()` (solo global) para lectura y escritura, ya que no se invoca con un cwd de proyecto.
+
+---
+
+## Evaluación de políticas
+
+`src/hooks/policy-evaluator.ts` ejecuta las políticas en orden.
+
+Para cada política:
+
+1. Busca el esquema `params` de la política (si tiene uno).
+2. Lee `policyParams[policy.name]` de la configuración combinada.
+3. Combina los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`.
+4. Llama a `policy.fn(ctx)` con el contexto resuelto.
+5. Si el resultado es `deny`, se detiene inmediatamente y devuelve esa decisión.
+6. Si el resultado es `instruct`, acumula el mensaje y continúa.
+7. Si el resultado es `allow`, continúa con la siguiente política.
+
+Después de que todas las políticas se ejecutan:
+- Si se devolvió algún `deny`, emite la respuesta deny.
+- Si se recopilaron respuestas `instruct`, emite una única respuesta instruct con todos los mensajes unidos.
+- De lo contrario, emite una respuesta allow (stdout vacío, salida 0).
+
+---
+
+## Políticas integradas
+
+`src/hooks/builtin-policies.ts` define las 39 políticas integradas como objetos `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;
+}
+```
+
+Las políticas que aceptan `params` declaran un `PolicyParamsSchema` con tipos y valores predeterminados para cada parámetro. El evaluador de políticas inyecta los valores resueltos en `ctx.params` antes de llamar a `fn`. Las funciones de política leen `ctx.params` sin comprobaciones de nulo porque los valores predeterminados siempre se aplican primero.
+
+La coincidencia de patrones dentro de las políticas usa tokens de comando analizados (argv), no coincidencia de cadenas sin procesar. Esto evita la elusión mediante inyección de operadores de shell (por ejemplo, un patrón para `sudo systemctl status *` no puede eludirse añadiendo `; rm -rf /` al comando).
+
+---
+
+## Políticas personalizadas
+
+`src/hooks/custom-hooks-registry.ts` implementa un registro respaldado por `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` carga el archivo de política del usuario:
+
+1. Lee `customPoliciesPath` de la configuración; omite si está ausente.
+2. Resuelve a ruta absoluta; verifica que el archivo exista.
+3. Reescribe todas las importaciones `from "failproofai"` a la ruta dist real para que `customPolicies` resuelva al mismo registro `globalThis`.
+4. Reescribe recursivamente las importaciones locales transitivas para garantizar la compatibilidad con ESM.
+5. Escribe archivos `.mjs` temporales e `import()`a el archivo de entrada.
+6. Llama a `getCustomHooks()` para recuperar los hooks registrados.
+7. Limpia todos los archivos temporales en un bloque `finally`.
+
+Ante cualquier error (archivo no encontrado, error de sintaxis, fallo de importación), el error se registra en `~/.failproofai/hook.log` y el cargador devuelve un array vacío. Las políticas integradas no se ven afectadas.
+
+Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada sigue interrumpiendo el procesamiento de las políticas personalizadas restantes (pero todos los integrados ya se habrán ejecutado en ese punto).
+
+---
+
+## Registro de actividad
+
+Después de cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai/hook-activity/current.jsonl`, que rota a `page-<timestamp>-<seq>.jsonl` una vez que alcanza el tamaño de página:
+
+```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 línea por política que tomó una decisión que no sea allow. Las decisiones allow no se registran (para mantener el archivo pequeño).
+
+---
+
+## Arquitectura del panel de control
+
+El panel de control es una aplicación **Next.js 16** que usa el App Router con React Server Components y Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Diseño raíz (tema, telemetría, navegación)
+  projects/page.tsx           ← Componente servidor: lista todos los proyectos Claude
+  project/[name]/page.tsx     ← Componente servidor: lista sesiones en un proyecto
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Componente servidor: renderiza el visor de sesión
+  policies/page.tsx           ← Componente cliente: gestión de políticas + registro de actividad
+  actions/
+    get-hooks-config.ts       ← Leer configuración + lista de políticas
+    update-hooks-config.ts    ← Activar/desactivar política
+    update-policy-params.ts   ← Actualizar parámetros de política
+    get-hook-activity.ts      ← Paginar/buscar en el registro de actividad
+    install-hooks-web.ts      ← Instalar/eliminar hooks desde el navegador
+  api/
+    download/[project]/[session]/route.ts   ← Exportación de sesión por CLI (JSONL o JSON)
+```
+
+**Flujo de datos:**
+
+- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyectos y sesiones directamente desde el sistema de archivos (sin capa de API para lecturas).
+- La página de políticas usa Server Actions para todas las mutaciones (activar/desactivar, actualizar parámetros, instalar/eliminar).
+- El visor de sesión analiza el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas.
+
+**Decisiones de diseño clave:**
+
+- Sin base de datos: todo el estado persistente está en archivos planos (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions para mutaciones: no se necesita API REST para operaciones CRUD.
+- React Server Components para páginas de lectura: carga inicial más rápida, sin bundle del cliente para obtención de datos.
+- Componentes cliente solo donde se necesita interactividad (activación de políticas, búsqueda de actividad, visor de registros).
+
+---
+
+## Estructura de archivos
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # Enrutador CLI (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Pipeline de eventos de hook
+│   ├── builtin-policies.ts       # 39 definiciones de políticas
+│   ├── policy-evaluator.ts       # Motor de ejecución de políticas
+│   ├── policy-registry.ts        # Registro y búsqueda de políticas
+│   ├── policy-types.ts           # Interfaces TypeScript
+│   ├── hooks-config.ts           # Carga de configuración de múltiples ámbitos
+│   ├── custom-hooks-registry.ts  # Registro de hooks respaldado por globalThis
+│   ├── custom-hooks-loader.ts    # Cargador ESM para hooks JS del usuario
+│   ├── manager.ts                # Operaciones de instalación / eliminación / listado
+│   ├── install-prompt.ts         # Prompt interactivo de selección de políticas
+│   ├── hook-logger.ts            # Registro en hook.log
+│   ├── hook-activity-store.ts    # Persistencia de actividad en hook-activity/
+│   └── llm-client.ts             # Cliente de API LLM (para políticas con IA)
+├── app/                          # Panel de control Next.js (páginas + server actions)
+├── lib/                          # Utilidades compartidas
+│   ├── projects.ts               # Enumerar proyectos Claude desde el sistema de archivos
+│   ├── log-entries.ts            # Analizar el formato JSONL de transcripciones Claude
+│   ├── paths.ts                  # Resolver rutas del sistema
+│   └── ...
+├── components/                   # Componentes React de UI compartidos
+├── contexts/                     # Proveedores de contexto React (tema, auto-refresco, telemetría)
+├── examples/                     # Archivos de hooks personalizados de ejemplo
+└── __tests__/                    # Pruebas unitarias y E2E
+```