failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/pt-br/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "Métricas de Performance"
+description: "Veja no instante em que seus modelos, ferramentas ou hooks ficam lentos ou aumentam sua fatura, e detecte um pico de latência na cauda antes que seus usuários percebam."
+---
+
+
+Veja no instante em que seus modelos, ferramentas ou hooks ficam lentos ou aumentam sua fatura, e detecte um pico de latência na cauda antes que seus usuários percebam. Três páginas dedicadas transformam tempos brutos em p50, p95 e p99 que você lê de relance.
+
+![A página Models exibindo um mapa de calor de latência, uma faixa de percentis e valores de tokens, custo e janela de contexto por modelo](/agenteye/images/models.png)
+*A página Models: um mapa de calor de latência, uma faixa de percentis e, por modelo, tokens, custo estimado e ocupação da janela de contexto.*
+
+## Pare de deixar as médias esconderem suas piores execuções
+
+Um número médio de latência é reconfortante e inútil: ele suaviza aquela chamada em cinquenta que trava e aciona seu plantão às 2h da manhã. As páginas Models, Tools e Hooks recusam fazer isso. Cada uma tem o mesmo formato, então você aprende uma vez:
+
+- Um **sparkline de 24 bins** para a tendência de relance: isso está piorando?
+- Uma **faixa de vitais** com latência p50, p95 e p99, para que a execução típica e a cauda fiquem lado a lado.
+- Um **mapa de calor de latência**, com 24 bins de tempo por buckets de latência, que mostra *quando* as chamadas lentas se agruparam.
+- Uma **faixa de percentis**: uma linha p50 com faixas sombreadas de p25 a p75 e p10 a p90 e pontos p99, para que a dispersão permaneça visível em vez de ser diluída na média.
+
+Um crosshair de hover compartilhado conecta o mapa de calor e a faixa, então um pico na cauda se alinha no tempo nos dois em vez de se esconder atrás de uma única linha de média. Encontre as três páginas na seção **observe** do seu dashboard, cada uma com escopo para sua organização e filtrável por intervalo de datas, ambiente, agente e sessão.
+
+## Models: veja exatamente o que cada modelo custa
+
+A página Models (exibida acima) responde às duas perguntas que uma fatura sempre levanta: qual modelo e quanto. Além da visão de latência compartilhada, ela adiciona **consumo de tokens por modelo**, **custo estimado** e **ocupação da janela de contexto**, para que o crescimento descontrolado de prompts e uma compactação iminente sejam visíveis antes de te surpreenderem.
+
+O Failproof AI Observability reconhece IDs de modelos comuns automaticamente. Se uma janela parecer incorreta, ou se você rodar um modelo próprio privado, corrija ou adicione um em **Settings**, em **model context windows**, e as leituras de ocupação se atualizam.
+
+## Tools: distinga o lento do quebrado
+
+Uma chamada de ferramenta pode ser lenta ou pode estar falhando silenciosamente, e você quer saber qual é o caso em segundos, não após vasculhar logs.
+
+![A página Tools exibindo o mapa de calor de latência e a faixa de percentis compartilhados ao lado de uma divisão de sucesso e falha e uma barra de distribuição de ferramentas](/agenteye/images/tools.png)
+*A página Tools: o mesmo mapa de calor e faixa de percentis, mais uma divisão de sucesso e falha e uma barra de distribuição de ferramentas.*
+
+Junto à visão de latência compartilhada, a página Tools adiciona uma **divisão de sucesso e falha** e uma **barra de distribuição de ferramentas**, para que você veja de relance em quais ferramentas você mais depende e quais estão consumindo seu orçamento de erros.
+
+## Hooks: identifique o hook e o gatilho exatos
+
+Quando um hook de ciclo de vida atrasa uma execução, "os hooks estão lentos" não é algo sobre o qual você pode agir. A página Hooks leva você até o que importa.
+
+![A página Hooks exibindo a latência detalhada por nome de hook e evento de gatilho sobre o mapa de calor e a faixa de percentis compartilhados](/agenteye/images/hooks.png)
+*A página Hooks: latência detalhada por nome de hook e evento de gatilho.*
+
+Sobre o mesmo mapa de calor de latência e faixa de percentis, a página Hooks detalha a atividade por **nome do hook** e **evento de gatilho**, para que você chegue ao único hook e ao único evento que precisam de atenção.
+
+## Relacionados
+
+- [Event stream](/pt-br/agenteye/event-stream): o rastro em tempo real, com código de cores, de cada evento.
+- [Sessions](/pt-br/agenteye/sessions): agrupe eventos em uma linha por execução e abra seu grafo de execução.
+- [Error tracking](/pt-br/agenteye/error-tracking): uma superfície de triagem unificada para tudo que o dashboard pinta de vermelho.
+- [Dashboards](/pt-br/agenteye/dashboards): visões consolidadas de toda a sua frota.

package/.next/standalone/docs-old/pt-br/architecture.mdx

@@ -0,0 +1,332 @@
+---
+title: Arquitetura
+description: "Como o handler de hooks, o carregamento de configurações e a avaliação de políticas funcionam internamente"
+icon: sitemap
+---
+
+Este documento explica como o failproofai funciona internamente: como o sistema de hooks intercepta chamadas de ferramentas do agente, como as configurações são carregadas e mescladas, como as políticas são avaliadas e como o dashboard monitora a atividade do agente.
+
+---
+
+## Visão geral
+
+O failproofai possui dois subsistemas independentes:
+
+1. **Hook handler** - Um subprocesso CLI rápido que o Claude Code invoca a cada chamada de ferramenta do agente. Avalia políticas e retorna uma decisão.
+2. **Agent Monitor (Dashboard)** - Uma aplicação web Next.js para monitorar sessões de agente e gerenciar políticas.
+
+Ambos os subsistemas compartilham arquivos de configuração em `~/.failproofai/` e no diretório `.failproofai/` do projeto, mas são executados como processos separados e se comunicam apenas pelo sistema de arquivos.
+
+---
+
+## Hook handler
+
+### Integração com o Claude Code
+
+Quando você executa `failproofai policies --install`, ele escreve entradas como esta no `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin.
+
+### Formato do 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`, o payload também contém `tool_result` com a saída da ferramenta.
+
+O handler impõe um limite de 1 MB para o stdin. Payloads que excedem esse limite são descartados e todas as políticas implicitamente permitem a operação.
+
+### Formato de resposta
+
+**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 (qualquer evento exceto Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Instruct no evento Stop:**
+- Código de saída: `2`
+- Motivo escrito no stderr (não no stdout)
+
+**Allow:**
+- Código de saída: `0`
+- stdout vazio
+
+**Allow com mensagem:**
+
+`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O hook handler escreve o seguinte JSON no **stdout** (não em um arquivo de configuração — esta é a resposta do handler ao Claude Code, assim como as respostas de deny e instruct acima):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Código de saída: `0` (a operação é permitida)
+- Quando múltiplas políticas retornam `allow` com uma mensagem, suas mensagens são unidas com quebras de linha em uma única string `additionalContext`
+- Se nenhuma política fornecer uma mensagem, o stdout fica vazio (como antes)
+
+### Pipeline de processamento
+
+`src/hooks/handler.ts` implementa o 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 o processo é executado em menos de 100ms para payloads típicos, sem chamadas a LLM.
+
+---
+
+## Carregamento de configuração
+
+`src/hooks/hooks-config.ts` implementa o carregamento de configuração em três escopos.
+
+```text
+[1] {cwd}/.failproofai/policies-config.json        ← projeto   (maior prioridade)
+[2] {cwd}/.failproofai/policies-config.local.json  ← local
+[3] ~/.failproofai/policies-config.json             ← global    (menor prioridade)
+```
+
+Lógica de mesclagem:
+- `enabledPolicies` - união deduplicada entre os três arquivos
+- `policyParams` - por chave de política, o primeiro arquivo que a define prevalece inteiramente
+- `customPoliciesPath` - o primeiro arquivo que a define prevalece
+- `llm` - o primeiro arquivo que a define prevalece
+
+O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto.
+
+---
+
+## Avaliação de políticas
+
+`src/hooks/policy-evaluator.ts` executa as políticas em ordem.
+
+Para cada política:
+
+1. Busca o schema de `params` da política (se houver).
+2. Lê `policyParams[policy.name]` da configuração mesclada.
+3. Mescla os valores fornecidos pelo usuário sobre os padrões do schema para produzir `ctx.params`.
+4. Chama `policy.fn(ctx)` com o contexto resolvido.
+5. Se o resultado for `deny`, interrompe imediatamente e retorna essa decisão.
+6. Se o resultado for `instruct`, acumula a mensagem e continua.
+7. Se o resultado for `allow`, continua para a próxima política.
+
+Após todas as políticas serem executadas:
+- Se algum `deny` foi retornado, emite a resposta de deny.
+- Se algum retorno de `instruct` foi coletado, emite uma única resposta de instruct com todas as mensagens unidas.
+- Caso contrário, emite uma resposta de allow (stdout vazio, saída 0).
+
+---
+
+## Políticas embutidas
+
+`src/hooks/builtin-policies.ts` define todas as 39 políticas embutidas 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;
+}
+```
+
+Políticas que aceitam `params` declaram um `PolicyParamsSchema` com tipos e valores padrão para cada parâmetro. O avaliador de políticas injeta os valores resolvidos em `ctx.params` antes de chamar `fn`. As funções de política leem `ctx.params` sem verificações de nulo porque os padrões são sempre aplicados primeiro.
+
+A correspondência de padrões dentro das políticas usa tokens de comando analisados (argv), não correspondência de strings brutas. Isso evita contorno via injeção de operadores shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado adicionando `; rm -rf /` ao comando).
+
+---
+
+## Políticas personalizadas
+
+`src/hooks/custom-hooks-registry.ts` implementa um registro baseado em `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` carrega o arquivo de política do usuário:
+
+1. Lê `customPoliciesPath` da configuração; ignora se ausente.
+2. Resolve para caminho absoluto; verifica se o arquivo existe.
+3. Reescreve todas as importações `from "failproofai"` para o caminho real do dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`.
+4. Reescreve recursivamente importações locais transitivas para garantir compatibilidade com ESM.
+5. Escreve arquivos `.mjs` temporários e importa o arquivo de entrada com `import()`.
+6. Chama `getCustomHooks()` para recuperar os hooks registrados.
+7. Remove todos os arquivos temporários em um bloco `finally`.
+
+Em caso de erro (arquivo não encontrado, erro de sintaxe, falha de importação), o erro é registrado em `~/.failproofai/hook.log` e o loader retorna um array vazio. As políticas embutidas não são afetadas.
+
+As políticas personalizadas são avaliadas após todas as políticas embutidas. Um `deny` de uma política personalizada ainda interrompe as políticas personalizadas seguintes (mas todos os embutidos já terão sido executados nesse ponto).
+
+---
+
+## Log de atividade
+
+Após cada evento de hook, o handler anexa uma linha JSONL ao `~/.failproofai/hook-activity/current.jsonl`, que é rotacionado para `page-<timestamp>-<seq>.jsonl` ao atingir o tamanho de uma 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
+}
+```
+
+Uma linha por política que tomou uma decisão diferente de allow. Decisões de allow não são registradas (para manter o arquivo pequeno).
+
+---
+
+## Arquitetura do dashboard
+
+O dashboard é uma aplicação **Next.js 16** que usa o App Router com React Server Components e Server Actions.
+
+```text
+app/
+  layout.tsx                  ← Layout raiz (tema, telemetria, nav)
+  projects/page.tsx           ← Server component: lista todos os projetos Claude
+  project/[name]/page.tsx     ← Server component: lista sessões em um projeto
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Server component: renderiza o visualizador de sessão
+  policies/page.tsx           ← Client component: gerenciamento de políticas + log de atividade
+  actions/
+    get-hooks-config.ts       ← Lê a configuração + lista de políticas
+    update-hooks-config.ts    ← Ativa/desativa política
+    update-policy-params.ts   ← Atualiza parâmetros de política
+    get-hook-activity.ts      ← Pagina/pesquisa o log de atividade
+    install-hooks-web.ts      ← Instala/remove hooks pelo navegador
+  api/
+    download/[project]/[session]/route.ts   ← Exportação de sessão por CLI (JSONL ou JSON)
+```
+
+**Fluxo de dados:**
+
+- Componentes de página chamam `lib/projects.ts` e `lib/log-entries.ts` para ler dados de projetos/sessões diretamente do sistema de arquivos (sem camada de API para leituras).
+- A página de Políticas usa Server Actions para todas as mutações (toggle, atualização de params, instalar/remover).
+- O visualizador de sessão analisa o formato de transcrição JSONL do Claude e renderiza uma linha do tempo de mensagens e chamadas de ferramentas.
+
+**Decisões de design principais:**
+
+- Sem banco de dados - todo o estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions para mutações - nenhuma API REST necessária para operações CRUD.
+- React Server Components para páginas de leitura - carregamento inicial mais rápido, sem bundle de cliente para busca de dados.
+- Client components apenas onde há necessidade de interatividade (toggles de política, busca de atividade, visualizador de log).
+
+---
+
+## Estrutura de arquivos
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # Roteador CLI (hook / dashboard / install / etc.)
+├── src/hooks/
+│   ├── handler.ts                # Pipeline de eventos de hook
+│   ├── builtin-policies.ts       # 39 definições de políticas
+│   ├── policy-evaluator.ts       # Motor de execução de políticas
+│   ├── policy-registry.ts        # Registro e lookup de políticas
+│   ├── policy-types.ts           # Interfaces TypeScript
+│   ├── hooks-config.ts           # Carregamento de configuração multi-escopo
+│   ├── custom-hooks-registry.ts  # Registro de hooks baseado em globalThis
+│   ├── custom-hooks-loader.ts    # Loader ESM para hooks JS do usuário
+│   ├── manager.ts                # Operações de instalar / remover / listar
+│   ├── install-prompt.ts         # Prompt interativo de seleção de políticas
+│   ├── hook-logger.ts            # Logging para hook.log
+│   ├── hook-activity-store.ts    # Persiste atividade em hook-activity/
+│   └── llm-client.ts             # Cliente de API LLM (para políticas com IA)
+├── app/                          # Dashboard Next.js (páginas + server actions)
+├── lib/                          # Utilitários compartilhados
+│   ├── projects.ts               # Enumera projetos Claude do sistema de arquivos
+│   ├── log-entries.ts            # Analisa o formato JSONL de transcrição do Claude
+│   ├── paths.ts                  # Resolve caminhos do sistema
+│   └── ...
+├── components/                   # Componentes React de UI compartilhados
+├── contexts/                     # Provedores de contexto React (tema, auto-refresh, telemetria)
+├── examples/                     # Exemplos de arquivos de hook personalizados
+└── __tests__/                    # Testes unitários e E2E
+```