sinapse-ai 7.3.3 → 7.4.0

package/.sinapse-ai/development/templates/chrome-brain/knowledge-base/chrome-brain.md

@@ -0,0 +1,161 @@
+# Chrome Brain — Browser Automation Capability
+
+> Cross-squad capability que da a TODOS os agents do SINAPSE o poder de
+> navegar, clonar, preencher, auditar e scrape qualquer site via Chrome real.
+> Auto-ativado. Sem comando manual. NSN Mode sempre ligado.
+
+---
+
+## Arquitetura
+
+```
+Chrome (porta 9222, perfil ~/.chrome-debug-profile)
+  ├── Chrome DevTools MCP (29 tools) — acoes rapidas, screenshots, Lighthouse
+  ├── dev-browser (Playwright) — scraping complexo, batch, headless
+  └── claude-in-chrome (Extension) — fallback visual, coordenadas de tela
+```
+
+**Prioridade de tooling:** CDP > dev-browser > claude-in-chrome
+
+**Auto-launch:** Hook PreToolUse roda `chrome-ensure` antes de qualquer tool chrome.
+Nao precisa rodar `chrome-debug` manualmente.
+
+---
+
+## Decisao de Tooling
+
+| Cenario | Ferramenta |
+|---------|-----------|
+| Click, fill, navegar | Chrome DevTools MCP |
+| Screenshot/snapshot | Chrome DevTools MCP |
+| Performance/Lighthouse | Chrome DevTools MCP |
+| Network/Console | Chrome DevTools MCP |
+| Scraping com logica JS | dev-browser evaluate() |
+| Batch/loops | dev-browser |
+| Headless | dev-browser --headless |
+| Iframe cross-origin | claude-in-chrome ou CDP Input.dispatchMouseEvent |
+| CAPTCHA | CDP mouse events no iframe (funciona cross-origin) |
+
+---
+
+## Patterns Validados
+
+### Form Filling
+
+**Multi-step forms (testado em 9 steps):**
+1. navigate_page → URL
+2. click → botao que abre form/modal
+3. wait_for → form renderizar
+4. Para cada step: take_snapshot → identificar tipo → fill/click → avancar
+5. Ultimo step: click enviar
+
+**Gotchas:**
+- Sempre take_snapshot ANTES de preencher (mapeia seletores)
+- Email duplicado retorna erro inline — ter fallback
+- `fill` aceita seletor CSS direto
+- Dropdowns: click no dropdown → click na opcao (nao fill)
+
+### Site Cloning
+
+**Fase 1 — Captura:**
+1. navigate_page → URL alvo
+2. take_screenshot (1 referencia)
+3. evaluate_script → document.documentElement.outerHTML
+4. evaluate_script → extrair fontes, cores, layout, breakpoints
+5. Scroll + screenshot nos pontos criticos (max 3-4)
+
+**Fase 2 — Analise:**
+- Identificar stack (Next.js? Vite? React? Vanilla?)
+- Mapear componentes (hero, nav, sections, footer)
+- Identificar animacoes (Three.js, GSAP, CSS, Framer Motion)
+- Identificar assets (modelos 3D, texturas, SVGs, fontes)
+
+**Fase 3 — Recriacao:**
+1. HTML single-file (inline CSS + JS)
+2. Clonar shaders se WebGL
+3. Testar em nova aba → comparar com original → iterar
+
+**Casos validados:**
+- itsoffbrand.com hero (orb WebGL, parallax, blend-mode) — 15min
+- sinapse.club face 3D (Three.js r183, WaltHead.obj, bloom) — 20min
+
+### Animacoes 3D via AI
+
+Workflow: navigate Gemini → prompt descritivo → aguardar geracao →
+evaluate_script extrair HTML → salvar arquivo → abrir em nova aba → validar
+
+### CAPTCHA
+
+| Estrategia | Resultado |
+|-----------|----------|
+| CDP Input.dispatchMouseEvent em iframe | FUNCIONA (bypassa cross-origin) |
+| evaluate_script em iframe CAPTCHA | NAO FUNCIONA (same-origin policy) |
+| Audio challenge reCAPTCHA | PENDENTE (promissor) |
+| Continue with Google | PENDENTE (pula CAPTCHA se logado) |
+
+**IMPORTANTE:** Apos 3-4 resolucoes corretas, Google detecta automacao e entra
+em loop. Parar e mudar estrategia. Nao insistir.
+
+---
+
+## NSN Mode — Nunca Diga Nunca
+
+**Protocolo ativo em TODOS os agents com Chrome Brain.**
+
+Quando encontrar barreira:
+1. **Classificar** — permission? technical? knowledge? external?
+2. **Buscar** — WebSearch/WebFetch por workaround/solucao
+3. **Tentar alternativas** — minimo 3 abordagens diferentes
+4. **Configurar e testar** — instalar deps, ajustar permissoes, validar
+5. **Repetir** — voltar ao passo 2 com novo contexto (max 5 ciclos)
+6. **Escalar** — apos 5 falhas, reportar ao usuario com detalhes
+
+**Anti-patterns:**
+- NUNCA dizer "nao consigo" sem ter tentado alternativas
+- NUNCA parar no primeiro erro
+- NUNCA assumir que algo e impossivel sem pesquisar
+- NUNCA pedir pro usuario fazer algo que o agent pode automatizar
+
+**Excecoes:** acoes destrutivas, pagamentos, violacao de leis → pedir confirmacao
+
+---
+
+## Session Management
+
+**Limites (prevencao de crash):**
+- Max 15 screenshots por sessao
+- Max 10 snapshots por sessao
+- Preferir evaluate_script sobre take_snapshot (mais leve)
+- Nunca screenshot + snapshot do mesmo estado
+- Fechar tabs desnecessarias
+- Salvar outputs em arquivo ANTES de acumular mais
+
+**Rotacao:** A cada ~12 screenshots, salvar handoff e sugerir nova sessao.
+
+---
+
+## Learnings Log
+
+> Secao atualizada automaticamente quando NSN Mode resolve problemas novos.
+> Formato: data, barreira, tentativas, solucao, generalizavel, squad.
+
+### 2026-03-27 — CAPTCHA reCAPTCHA via CDP
+**Barreira:** Iframe cross-origin do Google bloqueia evaluate_script
+**Tentativas:** evaluate_script (falhou) → cliclick (precisa permissao) → AppleScript (precisa permissao)
+**Solucao:** CDP Input.dispatchMouseEvent com coordenadas calculadas a partir da posicao do iframe
+**Generalizavel:** Sim — qualquer iframe cross-origin pode ser interagido via CDP raw events
+**Squad afetada:** Todas (form filling, signup flows)
+
+### 2026-03-27 — Chrome normal vs debug profile
+**Barreira:** chrome-ensure matava o Chrome normal do usuario
+**Tentativas:** pkill generico (matava tudo)
+**Solucao:** pgrep -f "user-data-dir=$PROFILE" — mata apenas instancias do debug profile
+**Generalizavel:** Sim — pattern para convivencia Chrome normal + debug
+**Squad afetada:** Todas
+
+### 2026-03-27 — Session crash por acumulo de screenshots (65MB)
+**Barreira:** 46 screenshots + 31 snapshots = 31.8 MB de imagens, request excedeu 20MB
+**Tentativas:** N/A (crash irrecuperavel)
+**Solucao:** Limitar a 15 screenshots/sessao, preferir evaluate_script, rotacionar sessoes
+**Generalizavel:** Sim — regra universal para qualquer sessao com browser automation
+**Squad afetada:** Todas

package/.sinapse-ai/development/templates/chrome-brain/rules/chrome-brain-autoload.md

@@ -0,0 +1,56 @@
+# Chrome Brain — Auto-Activation & Auto-Learning Rule
+
+> CRITICAL: This capability auto-activates and auto-learns. No command needed.
+
+## Auto-Activation
+
+When the user's prompt matches ANY of these patterns, Chrome Brain is active:
+
+- **Browser**: abrir/navegar/acessar site, URL, pagina, chrome, aba
+- **Cloning**: clonar/replicar/copiar site, pagina, hero, layout, animacao
+- **Forms**: preencher/cadastrar/signup/login formulario, form, conta
+- **Audit**: auditar/analisar/inspecionar site, performance, Lighthouse
+- **Scraping**: extrair/scrape/coletar dados, conteudo, HTML, CSS
+- **Animation**: animacao 3D, Three.js, WebGL, shader, canvas
+
+## Protocol
+
+1. Chrome connection is guaranteed by PreToolUse hook (chrome-ensure)
+2. Select tooling: CDP > dev-browser > claude-in-chrome
+3. Execute with NSN Mode enabled (never say "I can't" — try 3+ alternatives)
+4. Track screenshot count — max 15 per session
+5. Handoff results to domain squad when applicable
+
+## Auto-Learning — MANDATORY
+
+After completing ANY browser automation task, evaluate:
+
+1. **Did something unexpected happen?** (error, workaround, new pattern)
+2. **Did NSN Mode activate?** (barrier encountered and resolved)
+3. **Is the solution generalizable?** (useful for future sessions)
+
+If YES to any:
+- Append the learning to the `## Learnings Log` section in:
+  `~/.sinapse/sinapse/knowledge-base/chrome-brain.md`
+- Format:
+  ```
+  ### YYYY-MM-DD — [Summary]
+  **Barreira:** [description]
+  **Tentativas:** [what was tried]
+  **Solucao:** [what worked]
+  **Generalizavel:** sim/nao
+  **Squad afetada:** [which]
+  ```
+
+This ensures every session makes the next session smarter.
+
+## Session Management
+
+Track screenshots mentally. When approaching 12:
+1. Save current state to handoff file
+2. Suggest session rotation to user
+3. Never exceed 15 screenshots in a single session
+
+## Knowledge Base
+
+Full reference: `~/.sinapse/sinapse/knowledge-base/chrome-brain.md`

package/.sinapse-ai/development/templates/chrome-brain/scripts/chrome-brain-log.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# ============================================================================
+# chrome-brain-log — Session logger for Chrome Brain
+# ============================================================================
+# Called by PostToolUse hook. Logs tool usage and tracks screenshot count.
+# Cross-platform: macOS, Linux, Windows (Git Bash / MSYS2).
+#
+# Environment:
+#   HOOK_TOOL_NAME — Name of the tool that was used (set by Claude Code)
+#
+# Behavior:
+#   - Logs tool name + timestamp to ~/.chrome-brain/session-YYYYMMDD.log
+#   - Tracks screenshot count in ~/.chrome-brain/.screenshot-count
+#   - WARNING at 12 screenshots, CRITICAL at 15
+#   - ALWAYS exits 0 (never blocks the tool pipeline)
+#
+# Usage: chrome-brain-log
+# ============================================================================
+
+# IMPORTANT: No set -e here. This script must NEVER fail or block the tool.
+
+LOG_DIR="$HOME/.chrome-brain"
+TODAY="$(date +%Y%m%d)"
+LOG_FILE="$LOG_DIR/session-${TODAY}.log"
+COUNTER_FILE="$LOG_DIR/.screenshot-count"
+
+# Ensure log directory exists
+mkdir -p "$LOG_DIR" 2>/dev/null || true
+
+# ----------------------------------------------------------------------------
+# Read tool name from environment
+# ----------------------------------------------------------------------------
+TOOL_NAME="${HOOK_TOOL_NAME:-unknown}"
+TIMESTAMP="$(date +%H:%M:%S)"
+
+# ----------------------------------------------------------------------------
+# Append to session log
+# ----------------------------------------------------------------------------
+echo "$TIMESTAMP $TOOL_NAME" >> "$LOG_FILE" 2>/dev/null || true
+
+# ----------------------------------------------------------------------------
+# Track screenshot count and emit warnings
+# ----------------------------------------------------------------------------
+if echo "$TOOL_NAME" | grep -qE "take_screenshot|take_snapshot|screenshot"; then
+  # Read current count (default 0 if file missing or unreadable)
+  COUNT="$(cat "$COUNTER_FILE" 2>/dev/null)" || COUNT=0
+
+  # Validate that COUNT is numeric
+  case "$COUNT" in
+    ''|*[!0-9]*) COUNT=0 ;;
+  esac
+
+  COUNT=$((COUNT + 1))
+
+  # Write updated count
+  echo "$COUNT" > "$COUNTER_FILE" 2>/dev/null || true
+
+  # Emit warnings at thresholds
+  if [ "$COUNT" -ge 15 ]; then
+    echo "CRITICAL: ${COUNT} screenshots in this session. Session at risk of exceeding 20MB API limit. Save state NOW." >&2
+  elif [ "$COUNT" -ge 12 ]; then
+    echo "WARNING: ${COUNT} screenshots in this session. Consider saving state and rotating." >&2
+  fi
+fi
+
+# Always exit 0 — never block the tool pipeline
+exit 0

package/.sinapse-ai/development/templates/chrome-brain/scripts/chrome-debug.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+# ============================================================================
+# chrome-debug — Manual Chrome debug launch
+# ============================================================================
+# For users to run directly when they want to start/restart the debug session.
+# Cross-platform: macOS, Linux, Windows (Git Bash / MSYS2).
+#
+# Usage: chrome-debug [PORT]
+#   PORT defaults to 9222
+#
+# Behavior:
+#   1. If Chrome debug is already running, exits early (no-op)
+#   2. Kills only debug-profile Chrome instances (never the user's browser)
+#   3. Launches Chrome with remote debugging flags
+#   4. Waits for startup and reports result
+#
+# Exit codes:
+#   0 — Chrome debug is running
+#   1 — Failed to start Chrome debug
+# ============================================================================
+set -e
+
+PORT="${1:-9222}"
+CHROME_DEBUG_PROFILE="$HOME/.chrome-debug-profile"
+CDP="http://127.0.0.1:$PORT/json/version"
+MAX_WAIT=15  # seconds (more generous for manual use)
+
+# Colors (only when stdout is a terminal)
+if [ -t 1 ]; then
+  GREEN='\033[0;32m'
+  RED='\033[0;31m'
+  YELLOW='\033[1;33m'
+  CYAN='\033[0;36m'
+  NC='\033[0m'
+else
+  GREEN='' RED='' YELLOW='' CYAN='' NC=''
+fi
+
+# ----------------------------------------------------------------------------
+# Detect OS
+# ----------------------------------------------------------------------------
+UNAME="$(uname -s)"
+case "$UNAME" in
+  Darwin)  OS="macos"   ;;
+  Linux)   OS="linux"   ;;
+  MINGW*|MSYS*|CYGWIN*) OS="windows" ;;
+  *)
+    echo -e "${RED}ERROR: Unsupported OS: $UNAME${NC}" >&2
+    exit 1
+    ;;
+esac
+
+# ----------------------------------------------------------------------------
+# Locate Chrome binary
+# ----------------------------------------------------------------------------
+find_chrome() {
+  case "$OS" in
+    macos)
+      local chrome_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      if [ -x "$chrome_path" ]; then
+        echo "$chrome_path"
+        return 0
+      fi
+      ;;
+    linux)
+      for cmd in google-chrome google-chrome-stable chromium-browser chromium; do
+        if command -v "$cmd" &>/dev/null; then
+          command -v "$cmd"
+          return 0
+        fi
+      done
+      ;;
+    windows)
+      local local_app_data=""
+      if [ -n "$LOCALAPPDATA" ]; then
+        local_app_data="$(cygpath -u "$LOCALAPPDATA" 2>/dev/null || echo "")"
+      fi
+      for chrome_path in \
+        "/c/Program Files/Google/Chrome/Application/chrome.exe" \
+        "/c/Program Files (x86)/Google/Chrome/Application/chrome.exe" \
+        "${local_app_data:+$local_app_data/Google/Chrome/Application/chrome.exe}"; do
+        [ -z "$chrome_path" ] && continue
+        if [ -f "$chrome_path" ]; then
+          echo "$chrome_path"
+          return 0
+        fi
+      done
+      local win_path
+      win_path="$(cmd.exe /c "where chrome.exe" 2>/dev/null | tr -d '\r' | head -1)" || true
+      if [ -n "$win_path" ]; then
+        echo "$win_path"
+        return 0
+      fi
+      ;;
+  esac
+  return 1
+}
+
+# ----------------------------------------------------------------------------
+# Check if Chrome debug is reachable via CDP
+# ----------------------------------------------------------------------------
+check_cdp() {
+  curl -sf "$CDP" -o /dev/null --max-time 1 2>/dev/null
+}
+
+# ----------------------------------------------------------------------------
+# Kill only debug-profile Chrome instances
+# ----------------------------------------------------------------------------
+kill_debug_chrome() {
+  echo -e "${YELLOW}Stopping existing debug-profile Chrome instances...${NC}"
+  case "$OS" in
+    macos|linux)
+      local pids
+      pids="$(pgrep -f "user-data-dir=$CHROME_DEBUG_PROFILE" 2>/dev/null)" || true
+      if [ -n "$pids" ]; then
+        echo "$pids" | xargs kill 2>/dev/null || true
+        sleep 2
+        echo -e "  ${GREEN}Stopped${NC}"
+      else
+        echo -e "  ${CYAN}No debug instances found${NC}"
+      fi
+      ;;
+    windows)
+      local killed=0
+      powershell.exe -NoProfile -Command "
+        Get-CimInstance Win32_Process -Filter \"Name='chrome.exe'\" |
+        Where-Object { \$_.CommandLine -like '*user-data-dir=*chrome-debug-profile*' } |
+        ForEach-Object { Stop-Process -Id \$_.ProcessId -Force -ErrorAction SilentlyContinue }
+      " &>/dev/null && killed=1 || true
+      if [ "$killed" -eq 1 ]; then
+        sleep 2
+        echo -e "  ${GREEN}Stopped${NC}"
+      else
+        echo -e "  ${CYAN}No debug instances found${NC}"
+      fi
+      ;;
+  esac
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+echo -e "${CYAN}Chrome Debug Launcher${NC}"
+echo -e "  Port: $PORT"
+echo -e "  Profile: $CHROME_DEBUG_PROFILE"
+echo -e "  OS: $OS"
+echo ""
+
+# Step 1: Check if already running
+if check_cdp; then
+  echo -e "${GREEN}Chrome debug already running on port $PORT${NC}"
+  # Show version info
+  local_version="$(curl -sf "$CDP" --max-time 2 2>/dev/null)" || true
+  if [ -n "$local_version" ]; then
+    echo -e "  $(echo "$local_version" | grep -o '"Browser":"[^"]*"' 2>/dev/null || true)"
+  fi
+  exit 0
+fi
+
+# Step 2: Find Chrome
+CHROME_BIN="$(find_chrome)" || {
+  echo -e "${RED}ERROR: Google Chrome not found.${NC}" >&2
+  echo "" >&2
+  echo "Install Chrome from: https://www.google.com/chrome/" >&2
+  case "$OS" in
+    linux)
+      echo "Or try: sudo apt install google-chrome-stable" >&2
+      echo "    or: sudo snap install chromium" >&2
+      ;;
+  esac
+  exit 1
+}
+echo -e "  Chrome: $CHROME_BIN"
+
+# Step 3: Kill stale debug-profile instances
+kill_debug_chrome
+
+# Step 4: Launch Chrome
+echo -e "${CYAN}Launching Chrome with remote debugging on port $PORT...${NC}"
+
+case "$OS" in
+  macos|linux)
+    "$CHROME_BIN" \
+      --remote-debugging-port="$PORT" \
+      --user-data-dir="$CHROME_DEBUG_PROFILE" \
+      --no-first-run \
+      &>/dev/null &
+    ;;
+  windows)
+    start "" "$CHROME_BIN" \
+      --remote-debugging-port="$PORT" \
+      --user-data-dir="$CHROME_DEBUG_PROFILE" \
+      --no-first-run \
+      &>/dev/null 2>&1 || \
+    "$CHROME_BIN" \
+      --remote-debugging-port="$PORT" \
+      --user-data-dir="$CHROME_DEBUG_PROFILE" \
+      --no-first-run \
+      &>/dev/null &
+    ;;
+esac
+
+# Step 5: Wait for Chrome to become reachable
+echo -n "  Waiting"
+elapsed=0
+while [ "$elapsed" -lt "$MAX_WAIT" ]; do
+  if check_cdp; then
+    echo ""
+    echo -e "${GREEN}Chrome debug ready on port $PORT${NC}"
+    local_version="$(curl -sf "$CDP" --max-time 2 2>/dev/null)" || true
+    if [ -n "$local_version" ]; then
+      echo -e "  $(echo "$local_version" | grep -o '"Browser":"[^"]*"' 2>/dev/null || true)"
+    fi
+    echo ""
+    echo -e "  CDP endpoint: $CDP"
+    echo -e "  DevTools:     http://127.0.0.1:$PORT"
+    exit 0
+  fi
+  echo -n "."
+  sleep 1
+  elapsed=$((elapsed + 1))
+done
+
+echo ""
+echo -e "${RED}ERROR: Chrome failed to start with debugging after ${MAX_WAIT}s${NC}" >&2
+echo "" >&2
+echo "Troubleshooting:" >&2
+echo "  1. Close all Chrome windows and try again" >&2
+echo "  2. Delete the debug profile: rm -rf $CHROME_DEBUG_PROFILE" >&2
+echo "  3. Check if port $PORT is in use by another process" >&2
+exit 1