create-bk-agent 0.22.0 → 0.22.2

package/templates/base/orchestrator/soporte/flows/atencion-ticket.yaml

@@ -0,0 +1,159 @@
+version: 1
+id: atencion-ticket
+name: "Atención de Ticket — {{payload.ticket_id}}"
+description: >
+  Pipeline completo de atención a un ticket de soporte: triage y priorización,
+  resolución L1 con la base de conocimiento, comunicación al cliente con gate de
+  aprobación, y registro de aprendizajes en la KB.
+
+steps:
+  - id: s1-triage
+    agent: triage-agent
+    depends_on: []
+    task: |
+      Clasificar y priorizar el siguiente ticket de soporte entrante.
+
+      DATOS DEL TICKET:
+      - ID: {{payload.ticket_id}}
+      - Cliente: {{payload.cliente}}
+      - Plan/Tier: {{payload.plan}}
+      - Canal de entrada: {{payload.canal}}
+      - Asunto: {{payload.asunto}}
+      - Descripción del problema: {{payload.descripcion}}
+      - Información del entorno (si la proporcionó): {{payload.entorno}}
+
+      Producir el triage completo:
+
+      1. PRIORIDAD
+         - P1 Crítico: sistema caído, impacto en producción, sin workaround
+         - P2 Alto: funcionalidad core degradada, impacto en operaciones
+         - P3 Medio: bug con workaround disponible o feature parcialmente afectada
+         - P4 Bajo: consulta, mejora sugerida o cosmético
+
+      2. TIPO DE ISSUE
+         - Bug / Error técnico
+         - Consulta / "How to"
+         - Solicitud de feature / mejora
+         - Problema de rendimiento / performance
+         - Acceso / permisos / facturación
+         - Integración con terceros
+
+      3. ÁREA DE PRODUCTO AFECTADA
+         Identificar qué módulo, API o componente está involucrado basándose en la descripción.
+
+      4. NIVEL DE SOPORTE REQUERIDO
+         - L1: resoluble con documentación existente o procedimiento estándar
+         - L2: requiere investigación técnica, acceso a logs o análisis de código
+         - L3: requiere escalación a ingeniería, posible bug en producción
+
+      5. SLA APLICABLE
+         Tiempo de respuesta y resolución según prioridad y plan del cliente.
+
+      6. INFORMACIÓN FALTANTE
+         Lista de datos adicionales que necesitamos del cliente para resolver más rápido
+         (si aplica).
+
+      7. CONTEXTO PARA EL AGENTE DE SOPORTE
+         Resumen ejecutivo de 3-4 líneas con lo que sabe el siguiente agente para arrancar.
+
+  - id: s2-resolucion
+    agent: support-agent
+    depends_on: [s1-triage]
+    task: |
+      Resolver el ticket de soporte usando la base de conocimiento.
+
+      TRIAGE DEL TICKET:
+      {{steps.s1-triage.output}}
+
+      TICKET ORIGINAL:
+      - Cliente: {{payload.cliente}} (Plan: {{payload.plan}})
+      - Asunto: {{payload.asunto}}
+      - Descripción: {{payload.descripcion}}
+      - Entorno: {{payload.entorno}}
+
+      Produce la respuesta de soporte L1:
+
+      1. DIAGNÓSTICO
+         Qué está causando el problema según la descripción y la base de conocimiento.
+
+      2. SOLUCIÓN PASO A PASO
+         Instrucciones claras y numeradas para que el cliente resuelva el problema.
+         Si hay un workaround mientras se investiga la causa raíz, indicarlo primero.
+
+      3. VERIFICACIÓN
+         Cómo sabe el cliente que el problema se resolvió (qué debe ver/comprobar).
+
+      4. ESTADO DE RESOLUCIÓN
+         - RESUELTO: el problema tiene solución documentada y completa
+         - NECESITA_INFO: falta información del cliente para continuar
+         - ESCALAR_L2: el issue supera el alcance de L1, necesita investigación técnica
+         - WORKAROUND: hay solución temporal pero el root cause requiere L2
+
+      5. ARTÍCULOS DE KB UTILIZADOS
+         Lista de artículos o secciones de la documentación consultados (para tracking).
+
+  - id: s3-comunicacion
+    agent: communication-agent
+    depends_on: [s1-triage, s2-resolucion]
+    gate: true
+    gate_criteria:
+      - "La respuesta es clara y accionable — el cliente sabe exactamente qué hacer"
+      - "El tono es empático sin ser condescendiente"
+      - "Si el issue no se resuelve completamente, se explica el próximo paso y el tiempo estimado"
+      - "No se incluye jerga interna ni información confidencial"
+    task: |
+      Redactar la respuesta al cliente para el ticket {{payload.ticket_id}}.
+
+      TRIAGE:
+      {{steps.s1-triage.output}}
+
+      RESOLUCIÓN L1:
+      {{steps.s2-resolucion.output}}
+
+      DATOS DEL CLIENTE:
+      - Nombre: {{payload.cliente}}
+      - Canal: {{payload.canal}}
+      - Plan: {{payload.plan}}
+
+      Redactar la comunicación completa:
+
+      ## Asunto del email / título de la respuesta
+      Claro, específico, que transmita que estamos trabajando en ello.
+
+      ## Cuerpo de la respuesta
+      - Apertura: reconocer el problema con empatía (1-2 líneas, sin excesos)
+      - Diagnóstico explicado en términos del cliente (no jerga técnica interna)
+      - Solución o próximos pasos numerados y claros
+      - Tiempo estimado si el problema no está completamente resuelto
+      - Cierre: cómo contactarnos si la solución no funciona o hay preguntas
+
+      ## Notas internas (no van al cliente)
+      - Información de contexto para el agente que haga seguimiento
+      - Acciones pendientes del equipo de soporte
+
+  - id: s4-kb
+    agent: knowledge-agent
+    depends_on: [s2-resolucion, s3-comunicacion]
+    task: |
+      Analizar el ticket resuelto y proponer mejoras a la base de conocimiento.
+
+      TICKET: {{payload.asunto}}
+      TRIAGE: {{steps.s1-triage.output}}
+      RESOLUCIÓN: {{steps.s2-resolucion.output}}
+
+      Evaluar:
+
+      1. ¿EXISTE ARTÍCULO EN LA KB?
+         - SÍ, está actualizado → no se requiere acción
+         - SÍ, pero está desactualizado o incompleto → proponer actualización
+         - NO → proponer nuevo artículo
+
+      2. PROPUESTA DE CONTENIDO (si aplica)
+         Si se necesita crear o actualizar un artículo, redactar el borrador completo
+         siguiendo la estructura: título + descripción del problema + causa + solución
+         paso a paso + verificación + casos relacionados.
+
+      3. MEJORAS AL PROCESO
+         Si este ticket reveló un gap en el proceso de atención (pregunta frecuente no
+         documentada, procedimiento ambiguo, criterio de escalación poco claro), proponer
+         la mejora específica.

package/templates/base/orchestrator/soporte/flows/incidente-critico.yaml

@@ -0,0 +1,218 @@
+version: 1
+id: incidente-critico
+name: "Incidente Crítico — {{payload.incidente_id}}"
+description: >
+  Gestión de incidentes P1/P2: confirmación y escalación con gate, diagnóstico
+  técnico profundo, plan de resolución con gate de aprobación, comunicado externo
+  al cliente y postmortem para prevenir recurrencias.
+
+steps:
+  - id: s1-confirmacion
+    agent: triage-agent
+    depends_on: []
+    gate: true
+    gate_criteria:
+      - "La prioridad P1/P2 está correctamente justificada con el impacto real"
+      - "El alcance del incidente está definido (cuántos clientes, qué funcionalidades)"
+      - "Se identificó el canal de comunicación de crisis y los responsables en guardia"
+      - "Hay un War Room o canal de coordinación definido"
+    task: |
+      Confirmar y documentar el incidente crítico para activar el protocolo de respuesta.
+
+      DATOS DEL INCIDENTE:
+      - ID: {{payload.incidente_id}}
+      - Reportado por: {{payload.reportado_por}}
+      - Fecha/hora de detección: {{payload.hora_deteccion}}
+      - Descripción inicial: {{payload.descripcion}}
+      - Sistemas afectados: {{payload.sistemas_afectados}}
+      - Clientes impactados (estimado): {{payload.clientes_impactados}}
+      - Síntomas observados: {{payload.sintomas}}
+
+      Producir el documento de apertura del incidente:
+
+      1. CLASIFICACIÓN
+         - Prioridad confirmada: P1 / P2 con justificación
+         - Tipo de incidente: outage total / degradación / pérdida de datos / seguridad / rendimiento
+         - Sistemas afectados con nivel de impacto por sistema
+
+      2. ALCANCE DEL IMPACTO
+         - Clientes afectados (cantidad y segmento)
+         - Funcionalidades no disponibles o degradadas
+         - Impacto en negocio estimado (revenue, operaciones, reputación)
+
+      3. HIPÓTESIS INICIALES
+         3 hipótesis de causa raíz ordenadas por probabilidad.
+
+      4. PLAN DE RESPUESTA INMEDIATA
+         - Acciones en las próximas 15 minutos
+         - Responsable de cada acción (rol)
+         - Canal de coordinación del equipo (War Room)
+
+      5. COMUNICACIÓN INICIAL
+         - A quién notificar dentro de la empresa (escalación interna)
+         - Si se debe notificar proactivamente a clientes ahora o esperar diagnóstico
+
+  - id: s2-diagnostico
+    agent: technical-agent
+    depends_on: [s1-confirmacion]
+    task: |
+      Realizar el diagnóstico técnico profundo del incidente.
+
+      DOCUMENTO DE APERTURA DEL INCIDENTE:
+      {{steps.s1-confirmacion.output}}
+
+      INFORMACIÓN TÉCNICA DISPONIBLE:
+      - Sistemas afectados: {{payload.sistemas_afectados}}
+      - Síntomas: {{payload.sintomas}}
+      - Logs o errores disponibles: {{payload.logs}}
+      - Cambios recientes en producción: {{payload.cambios_recientes}}
+
+      Producir el diagnóstico técnico:
+
+      1. ANÁLISIS DE CAUSA RAÍZ
+         Evaluación de cada hipótesis con la evidencia disponible.
+         Conclusión: causa raíz confirmada o hipótesis más probable con nivel de confianza.
+
+      2. ÁRBOL DE IMPACTO
+         Qué sistemas dependen del sistema afectado y cómo se propaga el fallo.
+
+      3. OPCIONES DE RESOLUCIÓN
+         Para cada opción: descripción, tiempo estimado, riesgo, impacto secundario.
+         - Opción A (más rápida): workaround o rollback
+         - Opción B (más definitiva): fix en producción
+         - Opción C (si aplica): fallback o degraded mode
+
+      4. RECOMENDACIÓN
+         Qué opción ejecutar primero y por qué, con los pasos concretos.
+
+      5. RIESGOS DE LA INTERVENCIÓN
+         Qué puede salir mal al aplicar la solución y cómo mitigarlo.
+
+  - id: s3-plan-resolucion
+    agent: escalation-agent
+    depends_on: [s2-diagnostico]
+    gate: true
+    gate_criteria:
+      - "La opción de resolución elegida está aprobada por el responsable técnico"
+      - "Hay un rollback plan definido si la solución empeora el incidente"
+      - "El tiempo estimado de resolución está actualizado y es realista"
+      - "Se definió quién ejecuta cada paso (no puede quedar sin responsable asignado)"
+    task: |
+      Diseñar y coordinar el plan de resolución del incidente.
+
+      DIAGNÓSTICO TÉCNICO:
+      {{steps.s2-diagnostico.output}}
+
+      CONTEXTO DEL INCIDENTE:
+      ID: {{payload.incidente_id}} | Sistemas: {{payload.sistemas_afectados}}
+      Clientes impactados: {{payload.clientes_impactados}}
+
+      Producir el plan de resolución:
+
+      1. DECISIÓN DE RESOLUCIÓN
+         Opción elegida con justificación y aprobación requerida.
+
+      2. RUNBOOK DE EJECUCIÓN
+         Pasos numerados con:
+         - Acción específica
+         - Responsable (rol)
+         - Tiempo estimado
+         - Criterio de verificación (cómo saber que el paso funcionó)
+
+      3. ROLLBACK PLAN
+         Si el fix empeora el incidente, qué hacer en los primeros 5 minutos.
+
+      4. CRITERIO DE RESOLUCIÓN
+         Cómo sabemos que el incidente está cerrado (métricas, checks, confirmación).
+
+      5. COMUNICACIÓN DURANTE LA RESOLUCIÓN
+         - Cada cuánto actualizar a clientes (ej: cada 30 minutos)
+         - Qué decirle al equipo interno
+         - Cuándo declarar "resuelto" públicamente
+
+      6. EQUIPO DE GUARDIA
+         Roles y responsabilidades durante la ejecución del plan.
+
+  - id: s4-comunicado-externo
+    agent: communication-agent
+    depends_on: [s1-confirmacion, s3-plan-resolucion]
+    task: |
+      Redactar las comunicaciones externas para el incidente {{payload.incidente_id}}.
+
+      CONTEXTO DEL INCIDENTE:
+      {{steps.s1-confirmacion.output}}
+
+      PLAN DE RESOLUCIÓN:
+      {{steps.s3-plan-resolucion.output}}
+
+      Redactar los 3 comunicados necesarios:
+
+      ## 1. COMUNICADO DE APERTURA (enviar ahora)
+      - Qué está pasando (sin jerga técnica, en términos de impacto al cliente)
+      - Qué estamos haciendo para resolverlo
+      - Tiempo estimado de resolución (dar rango, no promesas exactas)
+      - Dónde ver actualizaciones (status page, canal de comunicación)
+      - Contacto para urgencias
+
+      ## 2. ACTUALIZACIONES DE PROGRESO (template reutilizable)
+      Template con placeholders para actualizar cada 30 minutos durante el incidente:
+      - [HORA] Estado actual
+      - [AVANCE] Qué se hizo
+      - [PRÓXIMOS PASOS] Qué sigue
+      - [ETA] Estimación actualizada
+
+      ## 3. COMUNICADO DE CIERRE
+      - Confirmación de que el incidente fue resuelto
+      - Descripción breve de qué pasó y cómo se resolvió (sin exponer vulnerabilidades)
+      - Medidas tomadas para que no vuelva a ocurrir
+      - Disculpas y reconocimiento del impacto
+      - Crédito/compensación si aplica según política
+
+  - id: s5-postmortem
+    agent: technical-agent
+    depends_on: [s2-diagnostico, s3-plan-resolucion, s4-comunicado-externo]
+    task: |
+      Redactar el documento de postmortem del incidente {{payload.incidente_id}}.
+
+      DIAGNÓSTICO TÉCNICO:
+      {{steps.s2-diagnostico.output}}
+
+      PLAN Y RESOLUCIÓN:
+      {{steps.s3-plan-resolucion.output}}
+
+      DATOS DEL INCIDENTE:
+      - Hora de detección: {{payload.hora_deteccion}}
+      - Sistemas afectados: {{payload.sistemas_afectados}}
+      - Clientes impactados: {{payload.clientes_impactados}}
+
+      Estructura del postmortem (blameless — sin culpables, solo sistemas y procesos):
+
+      ## Resumen Ejecutivo
+      3-4 líneas: qué pasó, cuánto duró, impacto total.
+
+      ## Timeline
+      Cronología minuto a minuto desde la detección hasta la resolución.
+
+      ## Causa Raíz
+      Causa técnica confirmada. Usar "5 Whys" para llegar al root cause real.
+
+      ## Factores Contribuyentes
+      Condiciones que hicieron posible o empeoraron el incidente.
+
+      ## Qué Funcionó Bien
+      Partes del proceso de respuesta que fueron efectivas.
+
+      ## Qué No Funcionó
+      Gaps en detección, respuesta, comunicación o herramientas.
+
+      ## Acciones Correctivas
+      Lista priorizada de mejoras con responsable y fecha límite:
+      - Acciones de remediación inmediata (ya implementadas)
+      - Acciones de prevención a corto plazo (< 2 semanas)
+      - Acciones estructurales a mediano plazo (< 3 meses)
+
+      ## Métricas del Incidente
+      - MTTD (Mean Time to Detect)
+      - MTTA (Mean Time to Acknowledge)
+      - MTTR (Mean Time to Resolve)
+      - Clientes impactados y duración del impacto

package/templates/base/orchestrator/soporte/orchestrator.yaml

@@ -0,0 +1,98 @@
+version: 1
+
+orchestrator:
+  name: "Orquestador de Soporte al Cliente"
+  provider: __PROVIDER_ID__
+  vault:
+    path: ./vault
+    embedder: simple          # change to "ollama" in production for better semantic search
+
+__PROVIDERS_BLOCK__
+
+flows:
+  - id: atencion-ticket
+    file: ./flows/atencion-ticket.yaml
+    trigger: "ticket|soporte|consulta|problema|error|bug|incidencia|reclamo|ayuda|no funciona|falla"
+
+  - id: incidente-critico
+    file: ./flows/incidente-critico.yaml
+    trigger: "incidente|crítico|caído|urgente|p1|p2|emergencia|producción|caída del sistema|outage"
+
+agents:
+  - id: triage-agent
+    name: "Agente de Triage"
+    description: >
+      Clasifica y prioriza tickets de soporte entrantes. Determina la urgencia (P1-P4),
+      el tipo de issue (bug, consulta, facturación, feature request), el área de producto
+      afectada y el nivel de soporte requerido (L1/L2/L3). Genera el contexto inicial
+      para el agente que tomará el ticket.
+    capabilities: [triage, clasificacion, prioridad, sla, routing, diagnostico-inicial]
+    provider: __PROVIDER_ID__
+    domain: soporte
+
+  - id: support-agent
+    name: "Agente de Soporte L1"
+    description: >
+      Maneja tickets de soporte de nivel 1: consultas frecuentes, configuraciones estándar,
+      procedimientos documentados y troubleshooting básico. Usa la base de conocimiento para
+      dar respuestas precisas y consistentes. Si no puede resolver, prepara el contexto
+      para escalación a L2 con toda la información necesaria.
+    capabilities: [l1, soporte, faq, troubleshooting, kb, resolucion, guia-paso-a-paso]
+    provider: __PROVIDER_ID__
+    domain: soporte
+
+  - id: technical-agent
+    name: "Agente Técnico L2"
+    description: >
+      Investigación técnica profunda de issues complejos. Diagnóstico de root cause,
+      análisis de logs, identificación de bugs, propuesta de workarounds y soluciones
+      definitivas. Documenta hallazgos técnicos para el equipo de ingeniería y para
+      enriquecer la base de conocimiento.
+    capabilities: [l2, tecnico, diagnostico, root-cause, logs, bugs, workaround, ingenieria]
+    provider: __PROVIDER_ID__
+    domain: soporte
+    gate: true
+    gate_criteria:
+      - "El diagnóstico incluye el root cause o una hipótesis sólida con evidencia"
+      - "Se propone al menos un workaround inmediato para desbloquear al cliente"
+      - "La solución propuesta no implica cambios de datos o configuración sin respaldo"
+      - "Se documentaron los pasos de reproducción del issue"
+
+  - id: escalation-agent
+    name: "Agente de Escalación L3"
+    description: >
+      Gestiona incidentes críticos y escalaciones a ingeniería. Coordina la respuesta
+      ante outages, define el plan de acción con responsables y tiempos, y asegura que
+      se mantenga informado al cliente durante todo el incidente. Lidera el proceso de
+      postmortem y seguimiento de acciones correctivas.
+    capabilities: [l3, escalacion, incidente, outage, coordinacion, postmortem, p1, p2]
+    provider: __PROVIDER_ID__
+    domain: soporte
+    gate: true
+    gate_criteria:
+      - "La escalación a ingeniería está justificada y el impacto está cuantificado"
+      - "Hay un responsable asignado (nombre o rol) para cada acción del plan"
+      - "El cliente fue notificado del incidente y del tiempo estimado de resolución"
+      - "Se definió el criterio de resolución: cómo sabemos que el incidente está cerrado"
+
+  - id: communication-agent
+    name: "Agente de Comunicación"
+    description: >
+      Redacta todas las comunicaciones hacia el cliente: respuestas a tickets, actualizaciones
+      de estado durante incidentes, emails de cierre, solicitudes de información adicional y
+      encuestas de satisfacción. Adapta el tono y nivel técnico al perfil del cliente.
+      Asegura que cada comunicación sea clara, empática y accionable.
+    capabilities: [comunicacion, redaccion, email, respuesta-cliente, estado, cierre, empatia]
+    provider: __PROVIDER_ID__
+    domain: soporte
+
+  - id: knowledge-agent
+    name: "Agente de Base de Conocimiento"
+    description: >
+      Mantiene y mejora la base de conocimiento de soporte. Identifica gaps de documentación
+      a partir de tickets resueltos, propone nuevos artículos o actualizaciones de los
+      existentes, y sugiere mejoras en los procedimientos de atención para reducir el tiempo
+      de resolución en futuros tickets similares.
+    capabilities: [knowledge-base, documentacion, kb, articulos, mejora-continua, procedimientos]
+    provider: __PROVIDER_ID__
+    domain: soporte

package/templates/base/orchestrator/soporte/test-flow.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+/**
+ * Test runner for the soporte orchestrator
+ *
+ * Usage:
+ *   node test-flow.mjs atencion-ticket    # standard ticket (triage → L1 → gate → KB)
+ *   node test-flow.mjs incidente-critico  # P1 incident (gate → diagnosis → gate → comms → postmortem)
+ *   node test-flow.mjs dynamic            # dynamic planning (no flow match)
+ */
+
+import { spawn }          from 'node:child_process';
+import { createInterface } from 'node:readline';
+import * as path          from 'node:path';
+import * as fs            from 'node:fs';
+import * as url           from 'node:url';
+
+const __dirname   = path.dirname(url.fileURLToPath(import.meta.url));
+const CONFIG_PATH = path.resolve(__dirname, 'orchestrator.yaml');
+const SERVER_PATH = path.resolve(
+    __dirname,
+    'node_modules/@backendkit-labs/orchestrator-agent/dist/server.js',
+);
+
+// ── Sample payloads ───────────────────────────────────────────────────────────
+
+const FLOWS = {
+    'atencion-ticket': {
+        flow_id: 'atencion-ticket',
+        task: 'Atender ticket de soporte: error al exportar reportes en formato Excel',
+        payload: {
+            ticket_id:   'TKT-2024-1547',
+            cliente:     'Acme Corp',
+            plan:        'Professional',
+            canal:       'Portal de soporte',
+            asunto:      'Error al exportar reportes en formato Excel — aparece "Download failed"',
+            descripcion: 'Desde ayer a la tarde, cuando intento descargar cualquier reporte en formato Excel (no en CSV), me aparece el mensaje "Download failed" y no se genera ningún archivo. El botón de descarga en PDF sí funciona bien. Lo probé en Chrome y Firefox con el mismo resultado. Necesito los reportes para una reunión de directorio mañana a las 10hs.',
+            entorno:     'Chrome 124, Windows 11, cuenta admin. La sesión expira correctamente y puedo hacer todo lo demás en la plataforma sin problemas.',
+        },
+    },
+    'incidente-critico': {
+        flow_id: 'incidente-critico',
+        task: 'Gestionar incidente crítico: plataforma inaccesible para clientes Enterprise',
+        payload: {
+            incidente_id:       'INC-2024-003',
+            reportado_por:      'Sistema de monitoreo + 3 clientes Enterprise simultáneamente',
+            hora_deteccion:     '2024-06-14 09:23 ART',
+            descripcion:        'La plataforma devuelve error 503 para todos los usuarios. El health check de la API principal está fallando. Múltiples clientes Enterprise están llamando al número de emergencias.',
+            sistemas_afectados: 'API principal (/api/v3/*), Dashboard web, Mobile app. La base de datos parece responder (status page de RDS en verde).',
+            clientes_impactados: 'Estimado 100% de usuarios activos en este momento (~340 sesiones activas según los últimos logs disponibles)',
+            sintomas:           'HTTP 503 en todas las rutas de la API. Los worker processes de Node.js no están respondiendo. Los logs muestran "FATAL: Cannot allocate memory" repetidamente desde las 09:18.',
+            logs:               'FATAL: Cannot allocate memory in static TLS block\nnode: Cannot allocate memory\nAborted (core dumped)\nRestarting worker... (intent 47 en los últimos 5 minutos)',
+            cambios_recientes:  'Deploy de v3.4.1 a las 08:45 (35 minutos antes del incidente). El deploy incluyó actualización de una dependencia de procesamiento de imágenes.',
+        },
+    },
+    'dynamic': {
+        flow_id: undefined,
+        task: process.env.TASK ?? 'Analizar los tickets de la última semana e identificar los 3 problemas más frecuentes que deberían documentarse como artículos de KB',
+        payload: {},
+    },
+};
+
+// ── MCP Client (stdio) ────────────────────────────────────────────────────────
+
+class McpClient {
+    constructor(serverPath) {
+        this._nextId  = 1;
+        this._pending = new Map();
+
+        const env    = { ...process.env };
+        const dotenv = path.join(__dirname, '.env');
+        if (fs.existsSync(dotenv)) {
+            for (const line of fs.readFileSync(dotenv, 'utf-8').split('\n')) {
+                const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*?)\s*$/);
+                if (m && m[2] && !(m[1] in env)) env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+            }
+        }
+
+        this._proc = spawn('node', [serverPath], { stdio: ['pipe', 'pipe', 'inherit'], env });
+
+        const rl = createInterface({ input: this._proc.stdout });
+        rl.on('line', (line) => {
+            if (!line.trim()) return;
+            try {
+                const msg = JSON.parse(line);
+                if (msg.id !== undefined && this._pending.has(msg.id)) {
+                    const { resolve, reject } = this._pending.get(msg.id);
+                    this._pending.delete(msg.id);
+                    if (msg.error) reject(new Error(msg.error.message ?? JSON.stringify(msg.error)));
+                    else resolve(msg.result);
+                }
+            } catch {}
+        });
+
+        this._proc.on('error', (err) => console.error('[MCP] error:', err.message));
+    }
+
+    _send(msg) { this._proc.stdin.write(JSON.stringify(msg) + '\n'); }
+
+    async initialize() {
+        const id = this._nextId++;
+        const p  = new Promise((res, rej) => this._pending.set(id, { resolve: res, reject: rej }));
+        this._send({ jsonrpc: '2.0', id, method: 'initialize', params: {
+            protocolVersion: '2024-11-05', capabilities: {},
+            clientInfo: { name: 'test-flow', version: '0.1.0' },
+        }});
+        await p;
+        this._send({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} });
+    }
+
+    async callTool(name, args) {
+        const id = this._nextId++;
+        const p  = new Promise((res, rej) => {
+            this._pending.set(id, { resolve: res, reject: rej });
+            setTimeout(() => {
+                if (this._pending.has(id)) { this._pending.delete(id); rej(new Error(`Timeout: ${name}`)); }
+            }, 120_000);
+        });
+        this._send({ jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } });
+        return p;
+    }
+
+    close() { this._proc.stdin.end(); }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const extractText = (r) => r?.content?.filter(c => c.type === 'text').map(c => c.text).join('\n') ?? String(r);
+const sleep       = (ms) => new Promise(r => setTimeout(r, ms));
+
+function printSection(title, text) {
+    const line = '─'.repeat(60);
+    console.log(`\n${line}\n  ${title}\n${line}`);
+    console.log(text);
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+    const flowKey = process.argv[2] ?? 'atencion-ticket';
+    const flowDef = FLOWS[flowKey];
+    if (!flowDef) {
+        console.error(`Unknown flow: ${flowKey}\nOptions: ${Object.keys(FLOWS).join(', ')}`);
+        process.exit(1);
+    }
+    if (!fs.existsSync(SERVER_PATH)) {
+        console.error(`Server not found:\n  ${SERVER_PATH}\nRun: npm install`);
+        process.exit(1);
+    }
+
+    console.log(`\nStarting orchestrator (soporte)...`);
+    console.log(`  Flow:   ${flowKey}`);
+
+    const client = new McpClient(SERVER_PATH);
+    try {
+        await client.initialize();
+        console.log('  MCP: connected ✓\n');
+
+        const runArgs = { config_path: CONFIG_PATH, task: flowDef.task };
+        if (flowDef.flow_id) runArgs.flow_id = flowDef.flow_id;
+        if (Object.keys(flowDef.payload).length > 0) runArgs.payload = flowDef.payload;
+
+        const startText = extractText(await client.callTool('orchestrator_run', runArgs));
+        printSection('RUN STARTED', startText);
+
+        const runIdMatch = startText.match(/runId:\s*`?([a-z0-9-]+)`?/i);
+        if (!runIdMatch) { console.error('\n[ERROR] Could not extract runId.'); process.exit(1); }
+        const runId = runIdMatch[1];
+
+        let attempts = 0, lastStatus = '';
+        console.log(`\nPolling (runId: ${runId})...\n`);
+
+        while (attempts < 80) {
+            await sleep(5000);
+            attempts++;
+
+            const statusText = extractText(await client.callTool('orchestrator_status', {
+                config_path: CONFIG_PATH, run_id: runId,
+            }));
+            const status = statusText.match(/status:\s*\*\*([^*]+)\*\*/)?.[1]
+                        ?? statusText.match(/^status:\s*(\S+)/m)?.[1]
+                        ?? 'unknown';
+
+            if (status !== lastStatus) {
+                process.stdout.write(`  [${new Date().toLocaleTimeString()}] status: ${status}\n`);
+                lastStatus = status;
+            }
+
+            if (status === 'complete') { printSection('RESULT', statusText); break; }
+            if (status === 'failed')   { printSection('ERROR', statusText); break; }
+
+            if (status === 'waiting_gate') {
+                printSection('GATE — APPROVAL REQUIRED', statusText);
+                console.log('\nAuto-approving...\n');
+                await sleep(2000);
+                const approveText = extractText(await client.callTool('orchestrator_approve', {
+                    config_path: CONFIG_PATH, run_id: runId,
+                    approved: true, notes: 'Auto-approved by test-flow.mjs',
+                }));
+                printSection('GATE APPROVED', approveText);
+                lastStatus = '';
+            }
+        }
+
+        if (attempts >= 80) console.log('\n[TIMEOUT] Check orchestrator_status manually.');
+    } finally {
+        client.close();
+    }
+}
+
+main().catch(err => { console.error('\n[FATAL]', err.message); process.exit(1); });