Tudex-Agent-Automator (TAA)

Tudex-Agent-Automator (TAA) es una herramienta de orquestación diseñada para automatizar el ciclo de vida de desarrollo de software utilizando la inteligencia de Jules.

El sistema lee definiciones de tareas desde archivos Markdown, crea sesiones en la API REST de Jules, monitorea el progreso y gestiona automáticamente los Pull Requests (PR) resultantes en GitHub.

• Triple Integración de IA: Soporte para Jules (SaaS), Gemini Code Assist CLI (Local/GCP), y Google AI Studio API (Programático gratuito).
• Definición de Agentes como Código: Define tareas e instrucciones en archivos Markdown simples y organizados por carpetas.
• Integración con Jules REST API: Utiliza la API moderna de Jules para crear sesiones y generar código.
• Pool de API Keys con Límite Diario: Configura múltiples API keys de Jules y el sistema las rota automáticamente, controlando el uso diario de cada una.
• Automatización de Pull Requests: Detecta automáticamente cuando Jules ha creado un PR.
• Verificación y Merge Automático: Espera a que pasen todos los checks de CI/CD de GitHub antes de fusionar (merge) el código de forma automática.
• Monitor Autónomo de PRs: Revisa cada 5 minutos los PRs abiertos de los repositorios cargados, intenta resolver ramas desfasadas, fusiona los PRs sanos y cierra los que fallan o quedan en conflicto irresoluble.
• Ejecución Concurrente por Repositorio: Ejecuta tareas simultáneamente a través de distintos repositorios, aplicando un modelo round-robin sobre los agentes de cada uno en iteraciones múltiples.
• Selección Interactiva: Permite seleccionar en la consola qué repositorios procesar en la ejecución actual.
• Integración con Gemini Code Assist (CLI Mode): Extiende las capacidades más allá de Jules utilizando el CLI de Google Cloud SDK (ggemini) para generar parches locales y automatizar cambios vía Git.

📋 Requisitos Previos

Para ejecutar este sistema, necesitarás:

1. Node.js: Versión 16 o superior.
2. Jules API Key: Una clave de API válida para acceder a jules.googleapis.com (SaaS de Jules.ai).
3. GEMINI API Key: (Opcional) Una API Key de Google AI Studio para usar el motor programático gratuito.
4. GitHub Token: Un Personal Access Token (PAT) con permisos de repo para gestionar PRs.
5. Google Cloud SDK: (Opcional) Instalado y autenticado vía gcloud auth login para usar el CLI localmente.

---

🔑 Resumen de Credenciales

Variable	Origen	Requerido para...
JULES_API_KEY	Jules.ai Dashboard	PRs automáticos (Agente autónomo).
GEMINI_API_KEY	Google AI Studio	Análisis programático (Costo $0).
GITHUB_TOKEN	GitHub Settings	Merge y gestión de repositorios.
(CLI Auth)	gcloud auth login	Automatización local y parchado Git.

---

🛠️ Instalación y Configuración

1. Clonar el repositorio e instalar dependencias:

   git clone https://github.com/aledotsoftware/Tudex-Agent-Automator.git
   cd Tudex-Agent-Automator
   npm install

2. Configurar Variables de Entorno: Crea un archivo .env en la raíz del proyecto basado en .env.example:

   # Credenciales
   GITHUB_TOKEN=ghp_TuGitHubTokenAqui
   JULES_API_KEY=TuJulesApiKeyAqui
   GITHUB_USERNAME=TuUsuarioGitHub
   
   # Pool de API Keys (separadas por coma, rotación automática)
   # JULES_API_KEYS=key1,key2,key3
   JULES_DAILY_LIMIT=5  # Máximo de sesiones por key por día
   
   # Configuración Opcional
   POLLING_INTERVAL=60000  # Intervalo de espera en ms (60 seg)
   LOG_LEVEL=info
   JULES_API_URL=https://jules.googleapis.com/v1alpha
   PR_MONITOR_ENABLED=1
   PR_MONITOR_RUN_ON_START=1
   PR_MONITOR_INTERVAL_MINUTES=5

🤖 Las Tres Vías de Inteligencia (AI Pillars)

TAA permite orquestar cambios utilizando tres motores distintos según la necesidad y el entorno:

1. Jules API (Motor Principal Asíncrono)

Es la forma original de TAA. Ideal para tareas complejas que requieren un agente de larga duración que genera Pull Requests automáticamente.

• Requiere: JULES_API_KEY.
• Uso: Automático al procesar agentes con provider: jules (default).

2. Gemini CLI (Ecosistema Local & Automation)

Utiliza el paquete oficial @google/gemini-cli para aplicar cambios directamente sobre tu sistema de archivos local de forma ultrarrápida.

¿Cómo sabe qué código modificar? Para el modo local, tú tienes el control total mediante parámetros en la terminal:

1. La Carpeta (--dir): Debes pasar la ruta absoluta a la carpeta raíz de tu repositorio (ej: P:\EterOS). El script se posicionará allí para ejecutar los cambios.
2. Los Archivos (--files): Puedes pasar una lista de archivos específicos (relativos a la raíz del repo) que quieres que la IA mejore.
3. El Contexto: La IA lee el contenido actual de esos archivos en tu disco duro.

• Comando de Ejemplo:

  # 1. Instalar CLI globalmente
  npm install -g @google/gemini-cli
  # 2. Login (una sola vez)
  gemini auth login
  # 3. Ejecutar parcheador
  python scripts/gemini_patcher.py `
    --dir "P:\MiProyecto" `
    --files "src/main.js" "README.md" `
    --agent "Vision"

• Requiere: Node.js instalado.
• Script Target: scripts/gemini_patcher.py.

3. Google AI Studio API (@google/generative-ai)

Utiliza la API gratuita para desarrolladores (Tier gratuito de AI Studio) que viene incluida en tu plan AI Pro.

• Uso: Integración programática directa en TAA sin costo adicional.
• Configuración: Requiere GEMINI_API_KEY en el archivo .env.
• Ventaja: Ventana de contexto masiva (hasta 2M de tokens) y costo $0.
• Obtención: Genera tu key en aistudio.google.com.
• Ideal para: Validación de código pre-merge, generación de documentación masiva y análisis de deuda técnica.
• Requiere: GEMINI_API_KEY (obtenida en aistudio.google.com).

---

📝 Estándar de Especificación de Agentes

Los agentes se definen en la carpeta agents/ siguiendo un estándar estricto para garantizar la orquestación automática.

🏗️ Estructura del Archivo .md

Cada archivo de agente debe contener un encabezado YAML (Frontmatter) cerrado entre triples guiones (---) y un cuerpo en Markdown.

---
repository: "usuario/repo"  # Repositorio destino (opcional si se infiere de la carpeta)
branch: "main"              # Rama base (default: main)
agent: "NombreAgente"       # Identificador único de la sesión
priority: 50                # Prioridad de ejecución (1-100, menor corre antes)
---

### 📋 Metadata
- **Alias:** @identificador
- **Category:** Categoria del Agente
- **Description:** Breve descripción de su propósito.

# [Nombre o Título de la Tarea]
[Instrucciones detalladas para Jules...]

🔑 Campos del Frontmatter (Obligatorios/Estándar)

Campo	Descripción	Notas
repository	Repositorio de GitHub (owner/repo).	Se auto-deduce si se omite basándose en la carpeta padre.
branch	Rama base para iniciar la tarea.	Por defecto main.
agent	ID único del agente.	Reemplaza al antiguo agent_id.
priority	Orden de ejecución en la cola.	10 (Crítico), 30 (Alto), 50 (Estándar), 70 (Bajo).
provider	Proveedor del modelo (jules o local).	Opcional. local usa LMStudio localmente.

📋 Gestión de Metadatos Adicionales

Para mantener el YAML limpio y compatible con el motor de orquestación, cualquier campo extra (como alias, category, description, version) debe colocarse en una sección de Metadata dentro del cuerpo de Markdown, no en el YAML. El script de estandarización mueve estos campos automáticamente para evitar errores de parseo en la API.

🌐 Contexto de Proyecto (.taa.md)

Puedes crear un archivo llamado .taa.md dentro de la carpeta de un proyecto (ej. agents/mi-repositorio/.taa.md). El contenido de este archivo se inyectará automáticamente al principio de las instrucciones de todos los agentes definidos en ese mismo nivel. Es ideal para proveer contexto general (estándares, archivos preferidos, descripciones de arquitectura) que todos los agentes del repositorio deben conocer.

🔑 Pool de API Keys y Configuración por Repositorio

Pool Global de Keys: Configura múltiples API keys de Jules en el .env raíz usando JULES_API_KEYS (separadas por coma). El sistema las rota automáticamente y controla el uso diario con JULES_DAILY_LIMIT (default: 5 sesiones por key por día). El tracking de uso se guarda en .jules-usage.json y se limpia automáticamente después de 7 días.

Keys por Repositorio (.keys.json) — Recomendado: Puedes crear un archivo .keys.json dentro de la carpeta de un proyecto para definir API keys de distintas cuentas/clientes que aportan a ese repo. Si existe, se usan exclusivamente estas keys (no las globales) para los agentes de ese repositorio.

Ejemplo: agents/mi-repositorio/.keys.json

{
  "keys": [
    { "name": "manu1", "key": "AQ.xxxxx" },
    { "name": "profellanes92-netizen", "key": "AQ.yyyyy" }
  ],
  "dailyLimit": 5
}

• keys: Array de objetos con name (nombre del cliente/cuenta) y key (API key de Jules).
• dailyLimit: Límite diario de sesiones por key para este repositorio (opcional, usa el global si no se especifica).

Override por Repositorio (.env) — Alternativa: También puedes crear un .env dentro de la carpeta del proyecto como alternativa más simple (pero sin nombres de cuenta).

• JULES_API_URL: URL de la API de Jules.

▶️ Ejecución y Proceso Interno

Para iniciar el orquestador:

npm start

Para dejarlo corriendo en loop de forma continua hasta detener el proceso manualmente:

npm run start:loop

También puedes arrancarlo directamente indicando repositorios y cantidad por vuelta:

node src/index.js loop all 1

El proceso seguirá relanzando tareas cuando las colas terminen. Para frenarlo, usa Ctrl+C o desactiva loop desde la consola interactiva/dashboard mientras el proceso siga vivo.

Servicio Cron Independiente (sin ejecución manual)

Ahora TAA incluye un servicio dedicado taa-cron que dispara corridas automáticamente contra el engine vía API (/api/run), sin requerir comandos manuales en consola.

Si quieres ejecutarlo localmente:

npm run start:cron

Variables de entorno del cron (también en .env.example):

• CRON_ENABLED=1
• CRON_ENGINE_URL=http://taa-engine:4005
• CRON_INTERVAL_MINUTES=15
• CRON_REPOS= (vacío = todos los repos)
• CRON_AGENTS_COUNT=1 (admite "all")
• CRON_RUN_ON_START=1
• CRON_SKIP_IF_BUSY=1 (evita disparar si el engine ya tiene tareas en running/queued)

Monitor de Pull Requests

El engine principal ahora incluye un monitor de PRs independiente del loop de agentes.

Comportamiento:

• cada 5 minutos (por defecto) revisa los PRs abiertos de los repositorios cargados en agents/
• si los checks pasan, intenta hacer merge automático
• si la rama está desfasada, intenta actualizarla desde la base con GitHub
• si los checks fallan, cierra el PR como rechazado
• si detecta conflicto de merge y GitHub no puede resolverlo automáticamente, cierra el PR

Variables:

• PR_MONITOR_ENABLED=1
• PR_MONITOR_RUN_ON_START=1
• PR_MONITOR_INTERVAL_MINUTES=5

Admin Web en contenedor

También puedes correr TAA como un contenedor con dashboard web integrado. El backend sirve el admin en / y mantiene el loop aunque no exista consola interactiva.

docker build -t taa-web .
docker run --rm -p 4005:4005 --env-file .env -v ${PWD}/tmp:/app/tmp taa-web

Después abre http://localhost:4005. Desde el panel puedes activar o desactivar el loop, y el estado queda persistido en tmp/runtime-config.json mientras mantengas ese volumen.

Para levantar engine + cron como servicios independientes:

docker compose up -d --build taa-engine taa-cron

Flujo Detallado de Ejecución:

1. Lectura y Detección (src/reader.js): El script lee todos los archivos .md en la carpeta agents/ de manera recursiva. Valida el Frontmatter e infiere los repositorios si no están explícitos, descartando aquellos sin configuración válida.
2. Agrupación: Se agrupan los agentes encontrados bajo su repositorio correspondiente.
3. Selección Interactiva (src/index.js): La terminal lista todos los repositorios detectados y pregunta al usuario (mediante readline) cuáles repositorios desea procesar. Puedes teclear "all" para todos, o números separados por coma (ej. 1,2).
4. Elección Manual o Automática:
   • El script pregunta si deseas elegir los agentes manualmente o de forma automática.
   • Si eliges de forma automática, te pide la cantidad de ejecuciones, seleccionando aleatoriamente el número de tareas a ejecutar (sin repetir agentes).
   • Si eliges manualmente, te muestra la lista de agentes disponibles por repositorio para que los escojas de forma interactiva (usando comas para elegir varios, ej: 1,3).
5. Ejecución Concurrente:
   • Dispara la ejecución de los agentes seleccionados de forma concurrente agrupados por sus respectivas iteraciones usando Promise.all().
6. Ciclo de Vida de cada Agente (processAgent):
   • Creación de Sesión: Envía una petición POST /sessions a la API de Jules con las instrucciones.
   • Polling: Realiza un ciclo de consulta (GET /sessions/{id}) esperando a que la tarea finalice y reporte un pullRequest.
   • Monitoreo de CI/CD: Una vez generado el PR, monitorea GitHub verificando periódicamente que los checks pasen correctamente.
   • Merge Automático: Cuando los checks son exitosos, el script procede al auto-merge del PR.
7. Automatización de Parches Locales (Gemini CLI):
   • Utiliza el script scripts/gemini_patcher.py para invocar el CLI de Gemini sobre archivos locales.
   • Genera sugerencias de mejora, las aplica y realiza commits automáticos en ramas de trabajo.
   • Ideal para tareas de refactorización estética ("Vision") y optimización de código base en segundos.

📂 Estructura del Proyecto

• src/index.js: Punto de entrada, lógica de concurrencia y orquestación general.
• src/reader.js: Búsqueda, lectura y parseo de frontmatter en los archivos Markdown de agentes. También lee .taa.md (contexto de proyecto) y .env (overrides por repo).
• src/jules.js: Cliente HTTP para crear sesiones y monitorearlas en la API REST de Jules. Integra el pool de keys.
• src/key-manager.js: Gestión del pool de API keys, rotación automática y tracking de uso diario.
• src/github.js: Cliente Octokit que evalúa estados de PR y realiza el merge en GitHub.
• src/cron-service.js: Scheduler independiente que dispara ejecuciones periódicas contra el engine.
• src/config.js: Gestión de variables de entorno y configuración.
• agents/: Carpeta con subdirectorios y archivos .md que contienen las tareas.
• .jules-usage.json: Archivo generado automáticamente para trackear el uso diario de cada API key.

⚠️ Solución de Problemas

• Error 401/403: Verifica que tus tokens (GITHUB_TOKEN y JULES_API_KEY) sean correctos y tengan permisos adecuados.
• Agente omitido ("Missing metadata"): Asegúrate de que el documento contiene en su Frontmatter un agent_id o agent, y que está dentro de una subcarpeta o declara un repository.
• Timeout esperando PR / Checks fallidos: Incrementa el POLLING_INTERVAL o revisa manualmente tu repositorio y panel de Jules. Si los tests fallan, el PR no se fusiona automáticamente.

---

Generado y mantenido de manera automatizada.