@gnpdev/rpa-tools 1.3.0 → 1.5.0

package/README.md

@@ -33,20 +33,20 @@ const pool = new Pool({
 
 // 2. Inicializa las herramientas
 export const rpa = await createRpaTools({
-  botId: process.env.RPA_BOT_ID,
-  db: pool,
-  minio: {
-    endPoint: process.env.MINIO_ENDPOINT,
-    port: parseInt(process.env.MINIO_PORT || '9000'),
-    useSSL: process.env.MINIO_USE_SSL === 'true',
-    accessKey: process.env.MINIO_ACCESS_KEY,
-    secretKey: process.env.MINIO_SECRET_KEY,
-    bucket: 'rpa-screenshots'
-  },
-  log: {
-    level: process.env.NODE_ENV === 'development' ? 'debug' : 'info',
-    pretty: process.env.NODE_ENV !== 'production',
-  }
+ botId: process.env.RPA_BOT_ID,
+ db: pool,
+ minio: {
+   endPoint: process.env.MINIO_ENDPOINT,
+   port: parseInt(process.env.MINIO_PORT || '9000'),
+   useSSL: process.env.MINIO_USE_SSL === 'true',
+   accessKey: process.env.MINIO_ACCESS_KEY,
+   secretKey: process.env.MINIO_SECRET_KEY,
+   bucket: 'rpa-screenshots'
+ },
+ log: {
+   level: process.env.NODE_ENV === 'development' ? 'debug' : 'info',
+   pretty: process.env.NODE_ENV !== 'production',
+ }
 })
 
 // 3. Exporta las herramientas
@@ -184,3 +184,99 @@ MINIO_SECRET_KEY=password
 MINIO_BUCKET=rpa-screenshots
 DATABASE_URL=postgres://user:pass@localhost:5432/db
 ```
+  screenshot: {
+    format: 'webp',
+    quality: 70,
+    captureQuality: 90,
+  },
+  // Opcional: Redis para live frame y heartbeat
+  redis: new Redis({ host: process.env.REDIS_HOST || 'localhost' }),
+  // Opcional: Gateway para registro centralizado de agentes
+  gateway: {
+    url: process.env.GATEWAY_URL,
+    apiKey: process.env.GATEWAY_API_KEY,
+    capabilities: ['screenshots'],
+  },
+})
+
+// 3. Exporta las herramientas
+export const { logger, state, step } = rpa;
+#### D. Live Frame (requiere Redis)
+Captura la página actual y sobrescribe SIEMPRE la misma key en MinIO (`live/{appId}/{instancia}/{usuario}/live.webp`).
+Una sola imagen por agente, ideal para monitoreo en tiempo real desde el frontend.
+
+```javascript
+import { rpa } from './lib/rpa.js';
+
+// Captura live (se actualiza en la misma key, no acumula)
+const result = await rpa.captureLive(page, {
+  usuario: 'agente-01',
+  instancia: process.env.HOSTNAME,       // opcional, default: HOSTNAME
+  fullPage: false,
+  metadata: { caso: 'INC-123' },
+});
+// result → { key: 'live/.../live.webp', updatedAt: '2026-06-05T...' }
+```
+
+Para marcar el agente como inactivo al finalizar:
+
+```javascript
+await rpa.setOffline({ usuario: 'agente-01' });
+// Sube un placeholder negro "AGENTE INACTIVO" a la misma key
+```
+
+### 6. Heartbeat y Estado del Agente en Redis
+Cuando configuras `redis` en `createRpaTools()`, el agente escribe su estado automaticamente:
+
+```javascript
+// Heartbeat periodico (Redis con TTL - expira solo si el agente crashea)
+await rpa.heartbeat('agente-01', { cpu: 45, memoria: 1024 });
+
+// Verificar si el agente debe pausarse (status === 'paused')
+const pausar = await rpa.shouldPause('agente-01');
+
+// Actualizar el caso activo
+await rpa.setCurrentCase('agente-01', 'INC-456');
+```
+
+**Keys en Redis:**
+| Key | TTL | Descripcion |
+| `agent:{usuario}:status` | 180s | `active` o `paused` |
+| `agent:{usuario}:heartbeat` | 120s | Ultimo heartbeat ISO |
+| `agent:{usuario}:current_case` | 180s | Caso activo |
+| `agent:{usuario}:screenshot_updated_at` | - | Timestamp del ultimo live frame |
+
+### 7. Gateway de Agentes (opcional)
+Si configuras `gateway` en `createRpaTools()`, el agente se registra automaticamente al iniciar
+y envia heartbeats cada 30s. El gateway centraliza el estado de todos los agentes.
+
+```javascript
+// El constructor ya lo hace automaticamente si gateway.url esta configurado:
+// - POST /agents/register al iniciar
+// - POST /agents/heartbeat cada 30s
+// - POST /api/instances/{id}/logs para logs (via createLogStream)
+
+// Opcionalmente, transmitir logs de Pino al gateway:
+import pino from 'pino';
+const logger = pino({
+  level: 'info',
+}, pino.multistream([
+  { stream: process.stdout },
+  { stream: rpa.gateway.createLogStream({ batchMs: 2000 }) },
+]));
+```
+
+**Propiedades:**
+```javascript
+if (rpa.gateway) {
+  console.log(rpa.gateway.gatewayUrl); // URL configurada
+  console.log(rpa.gateway.isConfigured); // true
+}
+```
+
+# Opcional: Redis para live frame y heartbeat
+REDIS_HOST=localhost
+REDIS_PORT=6379
+# Opcional: Gateway para registro centralizado
+GATEWAY_URL=http://gateway:3000
+GATEWAY_API_KEY=eyJhbGci...

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnpdev/rpa-tools",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Libreria para logs y screenshot de bots",
   "author": "Sergio Antonio Trujillo del Valle",
   "main": "src/index.js",

package/src/capture.js

@@ -9,6 +9,9 @@ const os = require('os');
  *  - capture()       → captura única con key timestampeda (histórica)
  *  - captureLive()   → sobrescribe siempre la misma key (live frame)
  *  - setOffline()    → sube placeholder negro a la key live (agente inactivo)
+ *  - heartbeat()     → escribe heartbeat del agente en Redis
+ *  - shouldPause()   → verifica si el agente debe pausarse
+ *  - setCurrentCase()→ actualiza el caso activo en Redis
  */
 class PageCapturer {
   /**
@@ -104,7 +107,6 @@ class PageCapturer {
         .webp({ quality: 70 })
         .toBuffer();
 
-      // Sobrescribe la misma key con headers anti-cache
       await this.minioClient.putObject(this.bucket, key, finalBuffer, finalBuffer.length, {
         'Content-Type': 'image/webp',
         'Cache-Control': 'no-cache, no-store, must-revalidate',
@@ -114,7 +116,6 @@ class PageCapturer {
 
       const timestamp = now.toISOString();
 
-      // Actualizar metadata en Redis
       if (this.redis) {
         await this.redis.set(`agent:${usuario}:screenshot_updated_at`, timestamp);
         await this.redis.set(`agent:${usuario}:screenshot_key`, key);
@@ -158,7 +159,6 @@ class PageCapturer {
     try {
       const key = `live/${this.botId}/${instancia}/${usuario}/live.webp`;
 
-      // Generar placeholder offline vía SVG (sharp lo rasteriza)
       let finalBuffer;
 
       try {
@@ -177,7 +177,6 @@ class PageCapturer {
           .webp({ quality: 50 })
           .toBuffer();
       } catch {
-        // Fallback: pixel negro 1x1 si SVG falla
         finalBuffer = await sharp({
           create: {
             width: 1,
@@ -188,7 +187,6 @@ class PageCapturer {
         }).webp().toBuffer();
       }
 
-      // Sobrescribe la misma key live con headers anti-cache
       await this.minioClient.putObject(this.bucket, key, finalBuffer, finalBuffer.length, {
         'Content-Type': 'image/webp',
         'Cache-Control': 'no-cache, no-store, must-revalidate',
@@ -198,7 +196,6 @@ class PageCapturer {
 
       const timestamp = new Date().toISOString();
 
-      // Actualizar Redis
       if (this.redis) {
         await this.redis.set(`agent:${usuario}:status`, 'paused');
         await this.redis.set(`agent:${usuario}:screenshot_updated_at`, timestamp);
@@ -218,7 +215,57 @@ class PageCapturer {
   }
 
   /**
-   * Libera recursos (Redis, etc.) — llamar al cerrar el bot.
+   * Escribe heartbeat del agente en Redis.
+   * TTL automatico: si el agente crashea, las keys expiran solas.
+   *
+   * @param {string} usuario - Identificador del usuario/agente
+   * @param {object} [metadata] - Metadatos adicionales
+   */
+  async heartbeat(usuario, metadata) {
+    if (!this.redis) return;
+    const now = new Date().toISOString();
+    const instancia = process.env.HOSTNAME || os.hostname();
+    const STATUS_TTL = 180;
+    const HEARTBEAT_TTL = 120;
+
+    await Promise.all([
+      this.redis.set('agent:' + usuario + ':status', 'active', 'EX', STATUS_TTL),
+      this.redis.set('agent:' + usuario + ':heartbeat', now, 'EX', HEARTBEAT_TTL),
+      this.redis.set('agent:' + usuario + ':instancia', instancia, 'EX', STATUS_TTL),
+      this.redis.set('agent:' + usuario + ':app_id', this.botId, 'EX', STATUS_TTL),
+      metadata && Object.keys(metadata).length > 0
+        ? this.redis.set('agent:' + usuario + ':metadata', JSON.stringify(metadata), 'EX', STATUS_TTL)
+        : Promise.resolve(),
+    ]);
+  }
+
+  /**
+   * Verifica si el agente debe pausarse (status === 'paused').
+   * @param {string} usuario
+   * @returns {Promise<boolean>}
+   */
+  async shouldPause(usuario) {
+    if (!this.redis) return false;
+    try {
+      const status = await this.redis.get('agent:' + usuario + ':status');
+      return status === 'paused';
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Actualiza el caso activo del agente en Redis.
+   * @param {string} usuario
+   * @param {string} caso
+   */
+  async setCurrentCase(usuario, caso) {
+    if (!this.redis) return;
+    await this.redis.set('agent:' + usuario + ':current_case', caso, 'EX', 180);
+  }
+
+  /**
+   * Libera recursos (Redis, etc.). Llamar al cerrar el bot.
    */
   async destroy() {
     if (this.redis && typeof this.redis.quit === 'function') {

package/src/gateway.js

@@ -0,0 +1,293 @@
+'use strict';
+
+const os = require('os');
+const { Writable } = require('stream');
+
+/**
+ * Cliente para gateway-browsers.
+ *
+ * Permite que rpa-tools se registre como agente en el gateway,
+ * envie heartbeats periodicamente, y transmita logs de Pino
+ * en tiempo real via REST API + WebSocket broadcast.
+ *
+ * Uso tipico:
+ *   const gateway = new GatewayClient({
+ *     gatewayUrl: 'http://gateway:3000',
+ *     apiKey:     process.env.GATEWAY_API_KEY,
+ *     botName:    'mi-bot',
+ *     instanceId: process.env.HOSTNAME || os.hostname(),
+ *   });
+ *   await gateway.register();
+ */
+class GatewayClient {
+  /**
+   * @param {object} opts
+   * @param {string}  opts.gatewayUrl - URL base del gateway (ej: http://gateway:3000)
+   * @param {string}  [opts.apiKey]   - Token JWT para autenticacion (opcional)
+   * @param {string}  opts.botName    - Nombre del bot (ej: 'avaya_chat')
+   * @param {string}  opts.instanceId - Identificador unico de esta instancia (pod)
+   * @param {string[]}[opts.capabilities] - Capacidades del agente (ej: ['screenshots', 'chat'])
+   * @param {object}  [opts.logger]   - Instancia de Pino para logs locales
+   */
+  constructor(opts = {}) {
+    this.gatewayUrl   = opts.gatewayUrl?.replace(/\/+$/, '');
+    this.apiKey       = opts.apiKey;
+    this.botName      = opts.botName;
+    this.instanceId   = opts.instanceId;
+    this.capabilities = opts.capabilities || [];
+    this.logger       = opts.logger;
+
+    this._registered  = false;
+    this._instanceDbId = null;
+    this._heartbeatTimer = null;
+  }
+
+  get isConfigured() {
+    return !!this.gatewayUrl;
+  }
+
+  async _fetch(path, options = {}) {
+    const url = `${this.gatewayUrl}${path}`;
+    const headers = {
+      'Content-Type': 'application/json',
+      ...(options.headers || {}),
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    const res = await fetch(url, {
+      method: options.method || 'GET',
+      headers,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+      signal: options.signal,
+    });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`Gateway ${res.status} on ${options.method || 'GET'} ${path}: ${text}`);
+    }
+
+    return res.json();
+  }
+
+  /**
+   * Registra esta instancia en el gateway.
+   * POST /agents/register
+   *
+   * @param {object} [opts]
+   * @param {string} [opts.hostname] - Hostname del pod
+   * @param {string} [opts.agentVersion] - Version del agente
+   * @param {string} [opts.platform] - Plataforma (linux, win32, etc.)
+   * @param {string} [opts.cdpUrl] - URL del CDP si el browser expone devtools
+   * @returns {Promise<{id: string, isNew: boolean}>}
+   */
+  async register(opts = {}) {
+    if (!this.isConfigured) return { id: null, isNew: false };
+
+    try {
+      const body = {
+        botName: this.botName,
+        instanceId: this.instanceId,
+        capabilities: this.capabilities,
+        hostname: opts.hostname || process.env.HOSTNAME || os.hostname(),
+        agentVersion: opts.agentVersion || process.env.npm_package_version || '1.0.0',
+        platform: opts.platform || process.platform,
+        cdpUrl: opts.cdpUrl || null,
+        metadata: {
+          pid: process.pid,
+          startedAt: new Date().toISOString(),
+        },
+      };
+
+      const result = await this._fetch('/agents/register', {
+        method: 'POST',
+        body,
+      });
+
+      this._registered = true;
+      this._instanceDbId = result.id;
+
+      if (this.logger) {
+        this.logger.info({
+          instanceDbId: result.id,
+          isNew: result.isNew,
+          gatewayUrl: this.gatewayUrl,
+        }, 'Agente registrado en gateway');
+      }
+
+      return { id: result.id, isNew: result.isNew };
+    } catch (err) {
+      if (this.logger) {
+        this.logger.error({ err, gatewayUrl: this.gatewayUrl }, 'Error registrando agente en gateway');
+      }
+      return { id: null, isNew: false };
+    }
+  }
+
+  /**
+   * Envia un heartbeat al gateway.
+   * POST /agents/heartbeat
+   *
+   * @param {object} opts
+   * @param {string} opts.status - Estado actual (running, paused, etc.)
+   * @param {string} [opts.currentStep] - Paso actual del bot
+   * @param {object} [opts.metrics] - Metricas (cpu, memory, uptime)
+   */
+  async heartbeat(opts = {}) {
+    if (!this.isConfigured || !this._registered) return;
+
+    try {
+      await this._fetch('/agents/heartbeat', {
+        method: 'POST',
+        body: {
+          instanceId: this.instanceId,
+          status: opts.status || 'running',
+          currentStep: opts.currentStep || null,
+          metrics: opts.metrics || undefined,
+        },
+      });
+    } catch (err) {
+      if (this.logger) {
+        this.logger.warn({ err }, 'Fallo heartbeat al gateway');
+      }
+    }
+  }
+
+  /**
+   * Envia un log estructurado al gateway.
+   * POST /api/instances/{instanceDbId}/logs
+   *
+   * @param {object} entry
+   * @param {string} entry.level   - trace | debug | info | warn | error | fatal
+   * @param {string} entry.message - Mensaje del log
+   * @param {string} [entry.source] - Origen (modulo/funcion)
+   * @param {object} [entry.metadata] - Metadatos adicionales
+   */
+  async sendLog(entry = {}) {
+    if (!this.isConfigured || !this._registered || !this._instanceDbId) return;
+
+    try {
+      await this._fetch(`/api/instances/${this._instanceDbId}/logs`, {
+        method: 'POST',
+        body: {
+          level: entry.level || 'info',
+          message: entry.message || '',
+          source: entry.source || null,
+          metadata: entry.metadata || undefined,
+        },
+      });
+    } catch {
+      // Silently fail — logs al gateway no deben romper el bot
+    }
+  }
+
+  /**
+   * Inicia el envio automatico de heartbeats periodicos.
+   * @param {number} intervalMs - Intervalo en ms (default: 30000)
+   */
+  startHeartbeat(intervalMs = 30000) {
+    if (!this.isConfigured || !this._registered) return;
+    this.stopHeartbeat();
+    this._heartbeatTimer = setInterval(() => {
+      this.heartbeat().catch(() => {});
+    }, intervalMs).unref();
+  }
+
+  /**
+   * Detiene heartbeats periodicos.
+   */
+  stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  /**
+   * Crea un stream Writable que puede usarse como destino adicional
+   * de Pino mediante pino.multistream().
+   *
+   * Los objetos de log recibidos se envian al gateway via POST /logs.
+   *
+   * @param {object} [opts]
+   * @param {number} [opts.batchMs=1000] - Intervalo de batch en ms
+   * @returns {import('stream').Writable}
+   */
+  createLogStream(opts = {}) {
+    const batchMs = opts.batchMs || 1000;
+    const self = this;
+    let buffer = [];
+    let timer = null;
+
+    const flush = () => {
+      const batch = buffer.splice(0);
+      if (batch.length === 0) return;
+      for (const entry of batch) {
+        self.sendLog(entry).catch(() => {});
+      }
+    };
+
+    const stream = new Writable({
+      objectMode: true,
+      write(chunk, encoding, callback) {
+        try {
+          const data = typeof chunk === 'string' ? JSON.parse(chunk) : chunk;
+
+          buffer.push({
+            level: data.level || 'info',
+            message: data.msg || data.message || JSON.stringify(data),
+            source: data.name || data.source || null,
+            metadata: {
+              ...(data.err ? { error: data.err.message, stack: data.err.stack } : {}),
+              ...(data.step ? { step: data.step } : {}),
+              ...(data.botId ? { botId: data.botId } : {}),
+              ...(data.reqId ? { reqId: data.reqId } : {}),
+            },
+          });
+
+          if (!timer) {
+            timer = setTimeout(() => {
+              timer = null;
+              flush();
+            }, batchMs).unref();
+          }
+
+          callback();
+        } catch (err) {
+          callback(err);
+        }
+      },
+
+      destroy(err, callback) {
+        if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        flush();
+        callback(err);
+      },
+
+      final(callback) {
+        if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        flush();
+        callback();
+      },
+    });
+
+    return stream;
+  }
+
+  /**
+   * Limpia recursos (timers).
+   */
+  destroy() {
+    this.stopHeartbeat();
+  }
+}
+
+module.exports = { GatewayClient };

package/src/index.d.ts

@@ -20,6 +20,31 @@ export interface ScreenshotConfig {
   /** Calidad de captura en Playwright. Default: 90 */
   captureQuality?: number;
 }
+// ── Opciones de Gateway Client ───────────────────────────────────────────────
+export interface GatewayConfig {
+  /** URL base del gateway (ej: http://gateway:3000). Default: process.env.GATEWAY_URL */
+  url?:          string;
+  /** Token JWT para autenticación. Default: process.env.GATEWAY_API_KEY */
+  apiKey?:       string;
+  /** Nombre del bot en el gateway. Default: botId */
+  botName?:      string;
+  /** ID de instancia (pod). Default: process.env.HOSTNAME */
+  instanceId?:   string;
+  /** Capacidades del agente */
+  capabilities?: string[];
+}
+
+export interface GatewayClient {
+  gatewayUrl: string;
+  isConfigured: boolean;
+  register: (opts?: Record<string, unknown>) => Promise<{ id: string | null; isNew: boolean }>;
+  heartbeat: (opts: { status: string; currentStep?: string; metrics?: Record<string, number> }) => Promise<void>;
+  sendLog: (entry: { level: string; message: string; source?: string; metadata?: Record<string, unknown> }) => Promise<void>;
+  startHeartbeat: (intervalMs?: number) => void;
+  stopHeartbeat: () => void;
+  createLogStream: (opts?: { batchMs?: number }) => any;
+  destroy: () => void;
+}
 // ── Opciones de captura live ─────────────────────────────────────────────────
 export interface CaptureLiveOptions {
   /** Identificador del usuario/agente */
@@ -56,6 +81,8 @@ export interface RpaToolsOptions {
   screenshot?: ScreenshotConfig;
   /** Cliente Redis opcional (ioredis). Requerido para captureLive/setOffline */
   redis?:      any;
+  /** Config de gateway-browsers (opcional). Si se provee, el agente se registra automaticamente */
+  gateway?:    GatewayConfig;
 }
 // ── Objeto retornado por createRpaTools ──────────────────────────────────────
 export interface RpaTools {
@@ -122,6 +149,24 @@ export interface RpaTools {
    * @param opts - Opciones (usuario, instancia)
    */
   setOffline: (opts?: { usuario?: string; instancia?: string }) => Promise<string | null>;
+    /**
+   * Escribe heartbeat del agente en Redis.
+   * Las keys tienen TTL. Requiere redis configurado en createRpaTools().
+   * @param usuario - Identificador del usuario/agente
+   * @param metadata - Metadatos adicionales
+   */
+  heartbeat: (usuario: string, metadata?: Record<string, unknown>) => Promise<void>;
+
+  /**
+   * Verifica si el agente debe pausarse (status === "paused" en Redis).
+   */
+  shouldPause: (usuario: string) => Promise<boolean>;
+
+  /**
+   * Actualiza el caso activo del agente en Redis.
+   */
+  setCurrentCase: (usuario: string, caso: string) => Promise<void>;
+
   /**
    * Captura screenshot, trace y registra error en base de datos.
    */
@@ -131,6 +176,8 @@ export interface RpaTools {
     err: Error;
     step?: string;
   }) => Promise<{ errorId: number | null; screenshotKey: string | null; traceKey: string | null }>;
+  /** Cliente del gateway-browsers (solo si configurado) */
+  gateway?:   GatewayClient;
   /** Detiene todos los intervalos. Llamar siempre al cerrar el bot. */
   destroy: () => void;
 }

package/src/index.js

@@ -1,10 +1,12 @@
 'use strict';
+const os                                      = require('os');
 const { createLogger }                       = require('./logger');
 const { createMinioClient, ensureBucket }    = require('./storage');
 const { ScreenshotWatcher }                  = require('./watcher');
 const { CredentialManager }                  = require('./credentials');
 const { captureError }                     = require('./errorCapture');
 const { PageCapturer }                      = require('./capture');
+const { GatewayClient }                      = require('./gateway');
 
 /**
  * Factory principal de la librería.
@@ -16,8 +18,14 @@ const { PageCapturer }                      = require('./capture');
  * @param {object}  [opts.log]          - opciones de Pino
  * @param {object}  [opts.screenshot]   - opciones de captura (formato, calidad)
  * @param {object}  [opts.redis]        - cliente Redis opcional (ioredis)
+ * @param {object}  [opts.gateway]      - config de gateway-browsers (opcional)
+ * @param {string}  [opts.gateway.url]  - URL del gateway (ej: http://gateway:3000)
+ * @param {string}  [opts.gateway.apiKey] - Token JWT para el gateway
+ * @param {string}  [opts.gateway.botName] - Nombre del bot en el gateway
+ * @param {string}  [opts.gateway.instanceId] - ID de instancia (default: HOSTNAME)
+ * @param {string[]}[opts.gateway.capabilities] - Capacidades del agente
  *
- * @returns {Promise<{ logger, state, step, watchDebugFlag, getCredentials, getCredentialsAll, updateAppStatus, isActive, capturePage, captureLive, setOffline, captureError, destroy }>}
+ * @returns {Promise<{ logger, state, step, watchDebugFlag, getCredentials, getCredentialsAll, updateAppStatus, isActive, capturePage, captureLive, setOffline, heartbeat, shouldPause, setCurrentCase, captureError, destroy, gateway }>}
  */
 async function createRpaTools(opts = {}) {
   const {
@@ -27,6 +35,7 @@ async function createRpaTools(opts = {}) {
     minio: minioCfg,
     screenshot: screenshotCfg,
     redis: redisClient,
+    gateway: gatewayCfg,
   } = opts;
 
   const minio = minioCfg ?? {
@@ -52,14 +61,41 @@ async function createRpaTools(opts = {}) {
   const credentials = new CredentialManager({ botId, pool: db });
   const capturer    = new PageCapturer({ botId, minioClient, bucket, logger, redis: redisClient });
 
+  // ── Gateway Client (opcional) ──────────────────────────────────────
+  const gateway = new GatewayClient({
+    gatewayUrl: gatewayCfg?.url || process.env.GATEWAY_URL,
+    apiKey:     gatewayCfg?.apiKey || process.env.GATEWAY_API_KEY,
+    botName:    gatewayCfg?.botName || botId,
+    instanceId: gatewayCfg?.instanceId || process.env.HOSTNAME || os.hostname(),
+    capabilities: gatewayCfg?.capabilities || [],
+    logger,
+  });
+
+  if (gateway.isConfigured) {
+    const reg = await gateway.register({
+      hostname: process.env.HOSTNAME || os.hostname(),
+      agentVersion: process.env.npm_package_version || '1.0.0',
+      platform: process.platform,
+    });
+
+    if (reg.id) {
+      gateway.startHeartbeat(30000);
+      logger.info({ instanceDbId: reg.id, gatewayUrl: gateway.gatewayUrl }, 'Gateway conectado');
+    }
+  }
+
   const state = { currentStep: 'Inicio' };
 
   return {
     logger,
     state,
+    gateway: gateway.isConfigured ? gateway : undefined,
     step: (name) => {
       state.currentStep = name;
       logger.info({ step: name }, 'Nuevo paso');
+      if (gateway.isConfigured) {
+        gateway.heartbeat({ status: 'running', currentStep: name }).catch(() => {});
+      }
     },
     /**
      * Inicia el polling que activa/desactiva screenshots según bot_debug_config.
@@ -113,6 +149,9 @@ async function createRpaTools(opts = {}) {
      * @returns {Promise<string|null>}
      */
     setOffline: (opts) => capturer.setOffline(opts),
+    heartbeat: (usuario, metadata) => capturer.heartbeat(usuario, metadata),
+    shouldPause: (usuario) => capturer.shouldPause(usuario),
+    setCurrentCase: (usuario, caso) => capturer.setCurrentCase(usuario, caso),
     /**
      * Captura screenshot y registra error en base de datos.
      */
@@ -130,6 +169,7 @@ async function createRpaTools(opts = {}) {
     destroy: () => {
       watcher.destroy();
       capturer.destroy().catch(() => {});
+      gateway.destroy();
     },
   };
 }