# Hyperion V2 - LLM-Native Universal Web Agent

[![CI](https://github.com/ericklrm89-jpg/hyperion/actions/workflows/ci.yml/badge.svg)](https://github.com/ericklrm89-jpg/hyperion/actions/workflows/ci.yml)

**El navegador más poderoso para IA.** Servidor MCP universal que permite a **cualquier** agente de IA (Claude, Cursor, Cline, OpenCode, etc.) controlar Chrome real con 5 motores de percepción, heartbeat resiliente, y visión en tiempo real.

```
CLAUDE CODE ──┐
CURSOR       ├─── MCP / CLI ──── HYPERION V2 ──── CDP ──── CHROME REAL
CLINE        │     (Zod schemas)   (5 engines)          (tus tabs, logins)
OPENCODE     ├─── Heartbeat + Auto-Reconnect
AGY          │     Real-Time Vision Streaming
CODEX        │     Overlay [0][1][2]...
HERMES       └─── Action Registry + Full Tracing
```

## 🚀 ¿Qué Hay de Nuevo en Hyperion V3.5?

> 📚 **Documentación Técnica Completa:** Consulta el [Historial de Desarrollo Técnico y Guía Operativa V3.5](HISTORIAL_DESARROLLO_TECNICO.md) para el detalle de arquitectura, lecciones aprendidas y flujos de producción.

### **1. Master Multi-Session Launcher & Supervisor (`launch-chrome-debug.bat`)**
- ✅ **Bypass Maestro con NTFS Directory Junction** → Enlace directo a nivel de kernel al perfil original `%LOCALAPPDATA%\Google\Chrome\User Data`, bypassando la restricción de seguridad de Chromium sin clonación ni copias y manteniendo 100% de logins y cuentas de Google y WhatsApp.
- ✅ **Selección Interactiva de Perfiles y Puertos** → Escaneo dinámico con timestamps de actividad, soporte de perfiles múltiples (`Erick ⭐`, `Default`, `Profile 1..N`) y puertos CDP independientes (`9001`, `9002`, `9222`, etc.).
- ✅ **Dashboard en Vivo con Comandos de Consola:**
  - `[s + Enter]` → Relanza la sesión seleccionada si se cerró la ventana.
  - `[n + Enter]` → Abre nueva pestaña o acceso directo (WhatsApp Web, Gmail, Facebook, Instagram, Gemini).
  - `[w + Enter]` → Inyecta suites preconfiguradas (Work Suite, Social Suite, AI Hub).
  - `[r + Enter]` → Refresca el estado y las pestañas en vivo.
  - `[q + Enter]` → Cierra la sesión y libera el puerto.

### **2. Inyección de Plantillas HTML Enriquecidas en Gmail (Trusted Types Bypass)**
- ✅ **Bypass de Políticas de Seguridad de Google** → Inyección de tablas comparativas, estilos CSS inline y badges mediante `document.execCommand('insertHTML')` con disparo reactivo de eventos `input` y `change`.
- ✅ **Consolidación de Destinatarios (Chip Commit)** → Emisión automática de evento `Enter` (VirtualKeyCode 13) para validar chips en el campo *"Para"*.

### **3. Subida de Archivos y Adjuntos Nativos (Cero Modales de SO)**
- ✅ **Inyección vía CDP `DOM.setFileInputFiles`** → Adjunta flyers, PDFs y fotos directamente sobre el `backendNodeId` de `input[type="file"]` sin invocar diálogos del explorador de Windows.

### **4. Capa Manus V3.2 Inmune a CSP**
- ✅ **Cero Dependencia de Etiquetas `<style>`** → 100% estilos inline directos con `cssText`.
- ✅ **Deduplicación Geométrica por Rejilla (`geoKey`)** → Elimina badges encimados priorizando botones e inputs.
- ✅ **Soporte Completo de Shadow DOM** → Mapeo recursivo profundo en componentes web encapsulados.
- ✅ **Bucle Dinámico 250ms con Singleton Guard** → Cero intervalos huérfanos y adaptación al scroll en SPAs.

## 📋 Arquitectura V2

```
src/
├── core/
│   ├── types.ts                    ← Universal types (16 interfaces)
│   ├── ActionRegistry.ts           ← Action execution + tracing + retries
│   └── logger.ts                   ← Structured pino logger (stderr-only for MCP)
│
├── connection/
│   ├── transport.ts                ← Base transport (CDP protocol)
│   ├── resilience/
│   │   ├── HeartbeatManager.ts     ← Health monitoring
│   │   ├── ReconnectionManager.ts  ← Auto-reconnect + exponential backoff
│   │   ├── ConnectionPool.ts       ← Metrics + connection pool
│   │   └── ConnectionHealthCheck.ts← Transport liveness probe
│   ├── attach.ts                   ← WebSocket attach mode (localhost:9222)
│   ├── launch.ts                   ← Fresh Chrome launch
│   └── extension.ts                ← Chrome extension mode
│
├── vision/
│   └── VisionEngine.ts             ← Real-time frame capture + change detection
│
├── overlay/
│   └── OverlayEngine.ts            ← Single-injection element mapping [0..N]
│
├── tools/
│   └── facebook/
│       └── postToFacebook.ts       ← Typed Facebook Reel & Post publisher
│
├── mcp/
│   ├── LLMServer.ts                ← 16+ registered actions with Zod schemas
│   └── MCPServerAdapter.ts         ← Stdio MCP protocol adapter
│
├── hyperion.ts                     ← Main client API
└── cli.ts                          ← CLI entry point (MCP / Interactive / Tool runner)

archive/                            ← Historial de prototipos DOM y scripts de testing
├── facebook-legacy/
├── instagram-legacy/
├── tiktok-legacy/
├── whatsapp-legacy/
└── exploratory/
```

## ⚠️ Términos de Servicio y Advertencia de Responsabilidad (ToS Risk)

> [!WARNING]
> **Aviso de cumplimiento normativo y políticas de plataformas:**
> Hyperion es una suite de automatización e interfaz de control de navegador basada en el protocolo estándar Chrome DevTools (CDP) diseñada para investigación, testing de interfaces, accesibilidad y flujos de trabajo asistidos por IA en cuentas propias o bajo consentimiento explícito.
> 
> La automatización e interacción con plataformas de terceros como **FB**, **TT**, **IG** o **WA** puede estar sujeta a políticas de uso y Términos de Servicio (ToS) específicos de cada proveedor. El desarrollador y usuario final asumen la responsabilidad exclusiva de cumplir con las directrices de dichas plataformas, evitar envíos automatizados no solicitados y mantener un uso ético y legítimo.

## 🎯 Casos de Uso

### Claude Code / Cursor / Cline
```bash
# Start MCP server
hyperion --mcp --launch

# Configure in your editor's settings
# Claude Code automatically discovers and uses all 16+ tools
```

### Así usa el LLM una acción:
```json
{
  "actionId": "overlay-inject",
  "input": {
    "refreshIntervalMs": 1000
  }
}
→ Response: {
    "injected": true,
    "elementCount": 42,
    "elements": [
      { "overlayId": 0, "text": "Click here", "x": 100, "y": 200 },
      { "overlayId": 1, "text": "Submit", "x": 150, "y": 250 },
      ...
    ]
  }
```

```json
{
  "actionId": "overlay-click",
  "input": { "overlayId": 5 }
}
→ Response: { "clicked": true, "overlayId": 5 }
```

## 📊 16+ Acciones Registradas

| Acción | Categoría | Perception | Timeout | Retry |
|--------|-----------|------------|---------|-------|
| `screenshot` | visual | visual | 5s | ✗ |
| `navigate` | navigation | none | 30s | ✓ (2x) |
| `click` | interaction | visual | 3s | ✓ (3x) |
| `type` | interaction | none | 5s | ✓ (2x) |
| `overlay-inject` | visual | visual | 5s | ✗ |
| `overlay-get` | visual | visual | 2s | ✗ |
| `overlay-click` | interaction | visual | 3s | ✓ (2x) |
| `overlay-kill` | visual | none | 2s | ✗ |
| `vision-start` | visual | visual | ∞ | ✗ |
| `vision-stop` | visual | none | ∞ | ✗ |
| `extract` | extraction | none | 5s | ✗ |
| `wait` | utility | none | 15s | ✗ |
| `scroll` | interaction | none | 3s | ✗ |
| `evaluate` | utility | none | 5s | ✗ |
| `hover` | interaction | visual | 2s | ✗ |
| `select-option` | interaction | none | 3s | ✗ |

## 🔧 Instalación

```bash
npm install -g hyperion-browser

# O desde source
git clone https://github.com/ericklrm89-jpg/hyperion.git
cd hyperion
npm install
npm run build
```

## 🎬 Quick Start

### Modo MCP (Claude Code, Cursor, etc.)
```bash
# Launch fresh Chrome + MCP server
hyperion --mcp --launch --port 9222

# O attach a Chrome existente
hyperion --mcp --attach ws://localhost:9222/devtools/page/xxx

# O usar extension
hyperion --mcp --extension
```

### CLI Interactivo
```bash
hyperion --launch

> navigate https://example.com
> screenshot
> click "button.submit"
> type "#email" "test@example.com"
> scroll down 500
> eval "document.title"
```

## 🏗️ Arquitectura de Pilares

### **PILAR 1: Core Types**
Definiciones universales compartidas por todo el sistema:
- `ActionDefinition<T>` → Schema Zod + metadata
- `ActionExecution` → Full tracing con screenshots
- `VisionFrame` → Frame con 30+ propiedades
- `ConnectionMetrics` → Health monitoring

### **PILAR 2: Resilience Layer**
**Heartbeat + Auto-Reconnect + Connection Pool**

```typescript
// Heartbeat detecta desconexiones
const hb = new HeartbeatManager(
  sender,
  onHealthChange,
  { maxMissed: 3, clientId: 'agent-1' }
);
hb.start(5000); // Ping cada 5s

// ReconnectionManager reintentos exponenciales
const rc = new ReconnectionManager({
  maxAttempts: 10,
  initialBackoffMs: 1000,
  maxBackoffMs: 30000,
  backoffMultiplier: 1.5,
});
await rc.executeWithReconnect(() => transport.call('Method'));

// ConnectionPool métricas
const pool = new ConnectionPool();
pool.recordMessageSent('conn-1', 'Page.navigate', 250);
const metrics = pool.getMetrics('conn-1');
// { state, messagesSent, averageLatency, errorCount, ... }
```

### **PILAR 3: Universal Action Framework**
**Ejecución segura + Retry + Tracing**

```typescript
const registry = new ActionRegistry();

// Registrar acción
registry.register({
  id: 'custom-action',
  name: 'My Action',
  description: '...',
  schema: z.object({ ... }),
  retry: { maxAttempts: 3, backoffMs: 1000 },
  timeout: 10000,
});

// Ejecutar con tracing
const execution = await registry.execute(
  'custom-action',
  { input: 'value' },
  async (validated) => {
    // Tu código aquí
    return result;
  },
  {
    captureScreenshots: true,
    beforeScreenshot: () => hyperion.screenshot.capture(),
    afterScreenshot: () => hyperion.screenshot.capture(),
  }
);

// execution contiene:
// - status, duration, attempts
// - output, error (si falló)
// - screenshots before/after/error
// - retry count y historial

registry.onExecution(exec => {
  console.log(`Action ${exec.actionId} -> ${exec.status} (${exec.duration}ms)`);
});
```

### **PILAR 4: Real-Time Vision**
**Streaming + Change Detection**

```typescript
const vision = new VisionEngine(hyperion);

// Start streaming
await vision.startStreaming(1000); // 1 frame/sec

vision.on('frame', (frame: VisionFrame) => {
  console.log(`Frame ${frame.id}:`);
  console.log(`  URL: ${frame.url}`);
  console.log(`  Elements: ${frame.elements.length}`);
  console.log(`  Platform: ${frame.platform}`);
  console.log(`  Changes: +${frame.changes?.added.length} -${frame.changes?.removed.length}`);
});

vision.on('frame-changed', (frame) => {
  // Solo elementos nuevos/removidos
  console.log('DOM cambió:', frame.changes);
});

const latest = vision.getLatestFrame();
const history = vision.getFrameHistory(10);
const stats = vision.getStats();

vision.stopStreaming();
```

### **PILAR 5: Overlay Engine**
**Inyección robusta + Auto-sync**

```typescript
const overlay = new OverlayEngine();

// Inyectar (una sola vez, garantizado)
await overlay.ensureInjected(hyperion, { refreshIntervalMs: 1000 });

// Obtener elementos
const elements = await overlay.getElements(hyperion);
// [
//   { overlayId: 0, text: 'Login', x: 100, y: 200 },
//   { overlayId: 1, text: 'Sign Up', x: 150, y: 200 },
// ]

// Click por ID
await overlay.clickById(hyperion, 5);

// Eliminar overlay
await overlay.kill(hyperion);
```

### **PILAR 6: LLM Server**
**MCP Bridge + 16+ Actions**

```typescript
const llmServer = new LLMServer(hyperion);

// Automáticamente registra 16+ acciones
const definitions = llmServer.getActionDefinitions();
// Cada una tiene schema Zod auto-documentado

// Ejecutar acción (como lo haría un LLM)
const result = await llmServer.executeAction('overlay-inject', {
  refreshIntervalMs: 1000,
});

// Ejecuta, trackea, captura screenshots, reintentos
const history = llmServer.getExecutionHistory(100);
const stats = llmServer.getStats();
```

## 🎛️ 3 Modos de Conexión

| Modo | Método | Anti-detección | Chrome 136+ | Recomendado |
|------|--------|---------------|-------------|-------------|
| **Extension** | Native Messaging | ✅ CreepJS 0% | ✅ Sin popup | ✅ **Default** |
| **Launch** | Fresh browser spawn | ✅ Full stealth | N/A | Para CI/aislado |
| **Attach** | WebSocket a browser existente | ⚠️ Parcial | ❌ Popup | Solo debugging |

## 🔒 Anti-Detección

- `Runtime.enable` OFF → Elimina runtime leak
- `Emulation.setAutomationOverride` → `navigator.webdriver = false` (nativo)
- Zero JS patches → Sin fingerprints
- Extension + Native Messaging → Evita popup de Chrome 136+
- `Emulation.setFocusEmulationEnabled` → Tabs en background no throttle

## 📈 Métricas y Debugging

```typescript
// Connection metrics
const pool = new ConnectionPool();
const metrics = pool.getMetrics('conn-1');
// {
//   state: 'connected',
//   messagesSent: 1250,
//   messagesReceived: 1240,
//   failedMessages: 2,
//   averageLatencyMs: 45.2,
//   errorCount: 1,
//   reconnectAttempts: 0
// }

// Action execution stats
const stats = registry.getStats();
// {
//   totalExecutions: 500,
//   successful: 495,
//   failed: 5,
//   successRate: 99%,
//   averageDurationMs: 234.5
// }

// Execution trace
const exec = registry.getExecutionById('action-id-123');
// {
//   status: 'success',
//   duration: 1234,
//   attempts: [
//     { attempt: 1, result: {...} },
//     { attempt: 2, error: '...' },
//     { attempt: 3, result: {...} }
//   ],
//   screenshots: [
//     { phase: 'before', base64: '...' },
//     { phase: 'after', base64: '...' }
//   ]
// }
```

## 🧪 Testing

```bash
# Unit tests
npm run test

# Integration tests
npm run test:integration

# Watch mode
npm run test -- --watch
```

## 📚 Documentación Completa

- **[Core API](./docs/API.md)** - Referencia completa
- **[Schema Definitions](./docs/SCHEMAS.md)** - Todos los Zod schemas
- **[Examples](./examples/)** - Ejemplos funcionales
- **[Architecture](./docs/ARCHITECTURE.md)** - Diagrama detallado

## 🤝 Integración con LLMs

### Claude Code
```json
{
  "mcpServers": {
    "hyperion": {
      "command": "hyperion",
      "args": ["--mcp", "--launch"]
    }
  }
}
```

### Cursor
En `.cursor/settings.json`:
```json
{
  "rules": {
    "hyperion": "hyperion --mcp --launch"
  }
}
```

### Cline
En cline_config.json:
```json
{
  "mcpServers": [
    {
      "name": "hyperion",
      "command": "npx hyperion --mcp --launch"
    }
  ]
}
```

## 📄 Licencia

MIT - Libre para uso comercial y personal

## 🚀 Roadmap V2.1

- [ ] Video recording integration
- [ ] Multi-tab management
- [ ] Advanced gesture support (swipe, pinch)
- [ ] Chrome DevTools integration
- [ ] Cloud persistence for execution logs
- [ ] Performance profiling hooks

## 💬 Support

- GitHub Issues: [hyperion/issues](https://github.com/ericklrm89-jpg/hyperion/issues)
- Discussions: [hyperion/discussions](https://github.com/ericklrm89-jpg/hyperion/discussions)

---

**Hyperion V2** - The LLM-native browser automation framework.

Built with 💚 for AI agents that want to automate the web properly.