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

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/

# Start MCP server
hyperion --mcp --launch

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

{
  "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 },
      ...
    ]
  }

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

npm install -g hyperion-browser

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

# 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

hyperion --launch

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

// 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, ... }

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)`);
});

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();

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);

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();

// 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: '...' }
//   ]
// }

# Unit tests
npm run test

# Integration tests
npm run test:integration

# Watch mode
npm run test -- --watch

{
  "mcpServers": {
    "hyperion": {
      "command": "hyperion",
      "args": ["--mcp", "--launch"]
    }
  }
}

{
  "rules": {
    "hyperion": "hyperion --mcp --launch"
  }
}

{
  "mcpServers": [
    {
      "name": "hyperion",
      "command": "npx hyperion --mcp --launch"
    }
  ]
}