Houdi | Agente IA para ejecución de tareas en español

Modo Actual (Proxy Terminal Directo)

Este fork está simplificado para operar como proxy directo entre el usuario, el modelo y la terminal:

• El usuario define un objetivo en lenguaje natural.
• El modelo responde un plan con pasos y comandos exactos.
• El agente muestra primero la explicación y luego ejecuta la secuencia de comandos.
• El resultado real de shell vuelve al ciclo hasta completar el objetivo.

Arranque rápido:

cp .env.example .env
# completar OPENAI_API_KEY
npm run cli

Contexto editable del modelo (proxy terminal):

• Archivo: docs/proxy-model-context.md
• Variable opcional: PROXY_MODEL_CONTEXT_FILE

Proyecto open source para arrancar un asistente de operación real por WhatsApp/Telegram/Slack, con arquitectura agéntica y enrutadores semánticos que puedes escalar.

Repositorio oficial:

• https://github.com/lichoudini/houdi-agent
• https://houdiagent.com

Versión actual: 0.63b
Autor del repositorio: licHoudini
Licencia: MIT (ver LICENSE)

Posicionamiento y comunicación del proyecto

• Houdi Agent es un proyecto open source orientado a operación real: ejecutar, verificar y auditar acciones.
• Se posiciona como blueprint de agente de implementación rápida (instalador + onboarding).
• Diferencial operativo: instalación y levantada en un único comando (bot + bridges opcionales).
• Inspiración de arquitectura: OpenClaw + Aurelio's Semantic Router.
• Diferencial: optimización desde el core para interpretar español operativo (AR/CL/MX) y casos ambiguos de lenguaje natural.
• Estado del producto: proyecto en desarrollo continuo con mejoras iterativas de interpretación y ejecución.
• Trabajo recomendado en iteración asistida con Chat GPT 5.3 para diseño de prompts, pruebas de intención y depuración semántica.

Compatibilidad de entorno

• Linux (incluyendo Ubuntu): compatible.
• macOS: compatible.
• Windows: compatible a través de WSL.
• Recomendación operativa: ejecutar preferentemente en Docker para minimizar problemas de compatibilidad por entorno.

Advertencia de seguridad de despliegue

Houdi Agent puede ejecutar acciones reales (archivos, tareas, shell y servicios según perfil).
Por seguridad, se recomienda instalarlo en entornos aislados y controlados: VMs, mini PC dedicadas o equipos segregados del entorno principal.

Buenas prácticas mínimas:

• Evitar instalación en equipos con datos sensibles no relacionados.
• Aplicar principio de mínimo privilegio en agentes y allowlists.
• Mantener DEFAULT_AGENT=operator como valor por defecto y operar con mínimo privilegio.
• operator arranca en modo workspaceOnly con allowlist explícita; reservar admin para sistema, rutas externas o tareas de alto privilegio.
• Revisar logs/auditoría durante las primeras semanas de operación.

Documentación

• docs/PROJECT.md: visión general del proyecto
• docs/ARCHITECTURE.md: arquitectura y flujo interno
• docs/RUNBOOK.md: operación diaria, rollout y troubleshooting
• docs/INSTALL.md: instalación paso a paso en otra PC
• docs/AGENT_MEMORY_BASELINE.md: baseline de memoria y personalidad
• docs/INTENT_ROUTER_HARDENING.md: pipeline, tuning y operación del enrutador de intenciones
• docs/RELEASE_NOTES_2026-02-21.md: cambios funcionales y operativos del release
• docs/RELEASE_NOTES_2026-02-23.md: mejoras de enrutado contextual, modo ECO y UX de comandos
• docs/RELEASE_NOTES_2026-02-24.md: soporte multi-proveedor IA (OpenAI/Claude/Gemini) y mejoras de onboarding
• docs/REPO_PUBLISH_GUARD.md: política y guard automático para push seguro
• LICENSE: licencia open source del proyecto (MIT)
• NOTICE.md: agradecimientos y avisos de marca/afiliación
• THIRD_PARTY_NOTICES.md: avisos de licencias de dependencias de terceros

Agradecimientos explícitos

• Gracias a OpenClaw.ai por inspiración de arquitectura agéntica operativa.
• Gracias a Aurelio.ai por inspiración en patrones de semantic routing.
• Gracias a OpenAI por capacidades fundacionales de API utilizadas en el proyecto.

Enfoque de seguridad del MVP

• Solo usuarios de Telegram autorizados (TELEGRAM_ALLOWED_USER_IDS)
• Ejecución sin shell (spawn), para reducir inyección
• Permisos por agente (agents/*.json) con allowlist de comandos
• Timeout por tarea

Este proyecto puede operar con privilegios altos si así lo configuras.

Permisos y Responsabilidad

• El perfil actual de agentes puede incluir comandos sensibles (por ejemplo sudo, systemctl, shutdown).
• El operador de la instancia es responsable de dónde se instala, qué usuario lo ejecuta y qué permisos del host concede.
• Para uso público, no compartas tu .env, tokens ni credenciales OAuth.
• Recomendado: usar un host dedicado para el agente y una cuenta de Telegram exclusiva para operación.

Publicación segura del repositorio

Antes de cada push:

npm run guard:repo

Para bloquear pushes inseguros automáticamente:

npm run hooks:install

Esto instala un pre-push que ejecuta el guard y rechaza pushes que incumplen política.

Perfiles de Despliegue

Perfil full-control (equipo propio y de confianza):

• Objetivo: máxima autonomía operativa.
• Mantener DEFAULT_AGENT=operator y cambiar temporalmente a admin solo para acciones puntuales.
• Ejecutar en host dedicado y con monitoreo de logs.

Perfil moderated (entorno compartido o más estricto):

• Objetivo: minimizar riesgo de ejecución accidental.
• Requerido: DEFAULT_AGENT=operator (default del proyecto).
• Para tareas sensibles, cambiar agente temporalmente: /agent set admin y luego volver a /agent set operator.
• Mantener operator como workspace-only y reservar admin para sistema, privilegios altos o rutas fuera del workspace.

Requisitos

• Node.js 22+
• Un bot token de Telegram (BotFather)
• Tu user ID de Telegram
• (Opcional) API key de OpenAI, Claude o Gemini para /ask y chat libre
• Para transcripción de audio se requiere OpenAI (OPENAI_API_KEY)

Recursos oficiales para instalación (usuarios nuevos)

• nvm (Node Version Manager): https://github.com/nvm-sh/nvm
• Node.js + npm: https://nodejs.org/en/download
• Guía oficial npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
• Git (descarga oficial): https://git-scm.com/downloads
• Docker Engine (instalación oficial): https://docs.docker.com/engine/install/
• Cómo clonar un repositorio: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository

Soporte IA multi-proveedor

• Proveedores soportados:
  • OpenAI (OPENAI_API_KEY)
  • Claude/Anthropic (ANTHROPIC_API_KEY)
  • Gemini (GEMINI_API_KEY)
• Selector global de proveedor: AI_PROVIDER=auto|openai|anthropic|gemini.
• AI_PROVIDER=auto usa prioridad: OpenAI -> Claude -> Gemini (si tienen key configurada).
• Puedes forzar modelo por chat con /model set <modelo> y el proveedor se detecta por prefijo:
  • gpt-*, o*, whisper-* -> OpenAI
  • claude-* -> Claude
  • gemini-* -> Gemini
• Capacidades por proveedor:
  • Texto (/ask, chat libre, síntesis): OpenAI / Claude / Gemini.
  • Visión (análisis de imagen): OpenAI / Claude / Gemini.
  • Audio (transcripción): OpenAI.

Configuración

Wizard recomendado (paso a paso por CLI):

npm run onboard

Instalador recomendado (entrypoint único):

./scripts/install-houdi-agent.sh

El instalador interactivo usa wizard en modo simple por default (primera instalación). Si necesitas control total de parámetros:

./scripts/install-houdi-agent.sh --wizard-mode advanced

Ayuda rápida del instalador:

./scripts/install-houdi-agent.sh --help

Modo automatizado (sin preguntas, ideal para provisionado):

TELEGRAM_BOT_TOKEN="<token>" TELEGRAM_ALLOWED_USER_IDS="123456789" \
./scripts/install-houdi-agent.sh --yes --accept-risk --service-mode user --install-deps --build

Instalación guiada en un comando (wizard paso a paso, sin editar .env manualmente):

git clone https://github.com/lichoudini/houdi-agent.git && cd houdi-agent && ./scripts/install-houdi-agent.sh

Instalación en un comando (bot + WhatsApp bridge):

git clone https://github.com/lichoudini/houdi-agent.git && cd houdi-agent && \
TELEGRAM_BOT_TOKEN="<token>" TELEGRAM_ALLOWED_USER_IDS="123456789" \
WHATSAPP_VERIFY_TOKEN="<verify-token>" WHATSAPP_ACCESS_TOKEN="<meta-token>" \
./scripts/install-houdi-agent.sh --yes --accept-risk --service-mode user --install-deps --build --with-whatsapp-bridge

Notas de operación del instalador:

• En --yes, valida antes de arrancar que existan TELEGRAM_BOT_TOKEN y TELEGRAM_ALLOWED_USER_IDS (por env o .env).
• Si falla onboarding, el instalador muestra pasos de recuperación accionables.
• Requiere Node.js >= 22.
• El onboarding ahora incluye configuración opcional de WhatsApp Cloud API (WHATSAPP_*).
• En service-mode user, puedes instalar opcionalmente houdi-slack-bridge.service y houdi-whatsapp-bridge.service.
• Usuarios no experimentados pueden usar el wizard interactivo para configurar todo sin abrir .env directamente.
• --wizard-mode simple (default): asistente con menos decisiones y defaults recomendados.
• --wizard-mode advanced: expone todos los parámetros técnicos.
• Flags de instalación directa:
  • --with-whatsapp-bridge: instala houdi-whatsapp-bridge.service al terminar onboarding.
  • --with-slack-bridge: instala houdi-slack-bridge.service al terminar onboarding.

Alias:

./scripts/houdi-onboard.sh

Si ejecutas onboarding en modo no interactivo parcial, puedes omitir la confirmación inicial de riesgo con:

npm run onboard -- --accept-risk

Si querés omitir preflight del instalador (no recomendado):

npm run onboard -- --skip-preflight

Flags útiles para automatización:

npm run onboard -- --yes --accept-risk --service-mode none
npm run onboard -- --yes --accept-risk --service-mode user --install-deps --build
npm run onboard -- --yes --accept-risk --service-mode system --force-system-install

Instalación detallada recomendada (paso a paso)

1. Preparar entorno aislado:

• VM / mini PC / host dedicado.
• Node.js 22+ y npm instalados.

2. Clonar repositorio:

git clone https://github.com/lichoudini/houdi-agent.git
cd houdi-agent

3. Ejecutar instalador guiado:

./scripts/install-houdi-agent.sh

4. Completar variables mínimas:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_ALLOWED_USER_IDS

5. Validar build y estado local:

npm run build
npm run cli -- memory status

6. Levantar runtime:

npm run start

7. Prueba funcional rápida en Telegram:

• /status
• crear una tarea
• ejecutar una acción simple de workspace

8. Endurecimiento inicial recomendado:

• validar DEFAULT_AGENT=operator en .env
• revisar perfil de agente activo y allowlist
• confirmar PROXY_RESET_WORKSPACE_ON_START=false para no vaciar el workspace en cada arranque
• habilitar solo capacidades necesarias

Configuración manual:

1. Instalar dependencias:

npm install

2. Crear .env:

cp .env.example .env

3. Completar variables en .env:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_ALLOWED_USER_IDS (ej. 123456789 o 123456789,987654321)
• HOUDI_WORKSPACE_DIR (default: ./workspace)
• HOUDI_CONTEXT_FILE_MAX_CHARS (default: 1800)
• HOUDI_CONTEXT_TOTAL_MAX_CHARS (default: 9000)
• HOUDI_MEMORY_MAX_RESULTS (default: 4)
• HOUDI_MEMORY_SNIPPET_MAX_CHARS (default: 320)
• HOUDI_MEMORY_MAX_INJECTED_CHARS (default: 1200)
• HOUDI_MEMORY_BACKEND (hybrid o scan, default: hybrid)
• HOUDI_SCHEDULE_POLL_MS (default: 15000)
• HOUDI_INTENT_ROUTER_DATASET_FILE (default: ./houdi-intent-router-dataset.jsonl)
• HOUDI_INTENT_ROUTER_ROUTES_FILE (default: ./workspace/state/intent-routes.json)
• HOUDI_INTENT_ROUTER_VERSIONS_FILE (default: ./workspace/state/intent-router-versions.json)
• HOUDI_INTENT_ROUTER_CHAT_ROUTES_FILE (default: ./workspace/state/intent-routes-by-chat.json)
• HOUDI_INTENT_ROUTER_CALIBRATION_FILE (default: ./workspace/state/intent-calibration.json)
• HOUDI_INTENT_ROUTER_HYBRID_ALPHA (default: 0.72, balance léxico vs char n-gram)
• HOUDI_INTENT_ROUTER_MIN_SCORE_GAP (default: 0.03, brecha mínima entre primer y segundo intent)
• HOUDI_INTENT_ROUTER_AB_ENABLED (default: false)
• HOUDI_INTENT_ROUTER_AB_SPLIT_PERCENT (default: 50)
• HOUDI_INTENT_ROUTER_AB_VARIANT_B_ALPHA (default: 0.66)
• HOUDI_INTENT_ROUTER_AB_VARIANT_B_MIN_GAP (default: 0.02)
• HOUDI_INTENT_ROUTER_AB_VARIANT_B_THRESHOLD_SHIFT (default: 0)
• HOUDI_INTENT_ROUTER_ROUTE_ALPHA_OVERRIDES_JSON (default: {}, override por ruta de alpha; ejemplo {"gmail":0.58,"workspace":0.8})
• HOUDI_INTENT_ROUTER_ALERT_PRECISION_MIN (default: 0.55)
• HOUDI_INTENT_ROUTER_ALERT_MIN_SAMPLES (default: 20)
• HOUDI_INTENT_ROUTER_HARD_NEGATIVES_ENABLED (default: true, minería automática de negativos desde dataset)
• HOUDI_INTENT_ROUTER_HARD_NEGATIVES_POLL_MS (default: 1800000)
• HOUDI_INTENT_ROUTER_HARD_NEGATIVES_READ_LIMIT (default: 4000)
• HOUDI_INTENT_ROUTER_HARD_NEGATIVES_MAX_PER_ROUTE (default: 10)
• HOUDI_INTENT_ROUTER_HARD_NEGATIVES_MIN_ADDED (default: 2)
• HOUDI_INTENT_ROUTER_CANARY_GUARD_ENABLED (default: true, auto-disable de canary si cae accuracy)
• HOUDI_INTENT_ROUTER_CANARY_GUARD_POLL_MS (default: 300000)
• HOUDI_INTENT_ROUTER_CANARY_GUARD_MIN_SAMPLES (default: 60)
• HOUDI_INTENT_ROUTER_CANARY_GUARD_MIN_ACCURACY (default: 0.55)
• HOUDI_INTENT_ROUTER_CANARY_GUARD_BREACHES_TO_DISABLE (default: 2)
• HOUDI_INTENT_SHADOW_MODE_ENABLED (default: false, evaluación en sombra del router alternativo sin ejecutar)
• HOUDI_INTENT_SHADOW_SAMPLE_PERCENT (default: 0, porcentaje de mensajes para shadow mode)
• HOUDI_INTENT_SHADOW_ALPHA (default: 0.66, peso léxico del router en sombra)
• HOUDI_INTENT_SHADOW_MIN_SCORE_GAP (default: 0.02, brecha mínima en sombra)
• HOUDI_INTENT_CLARIFICATION_TTL_MS (default: 300000, TTL de aclaraciones pendientes)
• HOUDI_SELFSKILL_DRAFTS_FILE (default: ./houdi-selfskill-drafts.json)
• HOUDI_INTERESTS_FILE (default: ./houdi-interests.json)
• HOUDI_SUGGESTIONS_ENABLED (default: true)
• HOUDI_SUGGESTIONS_MAX_PER_DAY (default: 15)
• HOUDI_SUGGESTIONS_MIN_INTERVAL_MINUTES (default: 90)
• HOUDI_SUGGESTIONS_MIN_OBSERVATIONS (default: 10)
• HOUDI_SUGGESTIONS_POLL_MS (default: 600000)
• HOUDI_AGENT_POLICY_FILE (default: ./workspace/state/agent-policy.json)
• HOUDI_AGENTIC_CANARY_PERCENT (default: 100, rollout por chat de controles agénticos)
• AI_PROVIDER (auto|openai|anthropic|gemini, default: auto)
• OPENAI_API_KEY (opcional)
• OPENAI_MODEL (default: gpt-4o-mini)
• ANTHROPIC_API_KEY (opcional, habilita Claude)
• ANTHROPIC_MODEL (default: claude-3-5-sonnet-latest)
• GEMINI_API_KEY (opcional, habilita Gemini)
• GEMINI_MODEL (default: gemini-2.0-flash)
• OPENAI_MAX_OUTPUT_TOKENS (default: 350)
• HOUDI_PROGRESS_NOTICES (default: false, muestra/oculta avisos intermedios con variantes cómicas de estado mientras piensa/carga)
• OPENAI_AUDIO_MODEL (default: whisper-1)
• OPENAI_AUDIO_LANGUAGE (default sugerido: es)
• OPENAI_AUDIO_MAX_FILE_BYTES (default: 20000000, 20MB)
• HOUDI_FILE_MAX_FILE_BYTES (default: 50000000, 50MB)
• HOUDI_IMAGE_MAX_FILE_BYTES (default: 20000000, 20MB)
• HOUDI_DOC_MAX_FILE_BYTES (default: 25000000, 25MB)
• HOUDI_DOC_MAX_TEXT_CHARS (default: 15000)
• ENABLE_WEB_BROWSE (default: true)
• WEB_SEARCH_MAX_RESULTS (default: 5)
• WEB_FETCH_TIMEOUT_MS (default: 20000)
• WEB_FETCH_MAX_BYTES (default: 2000000)
• WEB_CONTENT_MAX_CHARS (default: 15000)
• ENABLE_GMAIL_ACCOUNT (default: false)
• GMAIL_CLIENT_ID (OAuth client ID)
• GMAIL_CLIENT_SECRET (OAuth client secret)
• GMAIL_REFRESH_TOKEN (refresh token del usuario Gmail)
• GMAIL_ACCOUNT_EMAIL (opcional, solo informativo)
• GMAIL_MAX_RESULTS (default: 10)
• HOUDI_LOCAL_API_ENABLED (default: true, habilita bridge local CLI->bot)
• HOUDI_LOCAL_API_HOST (default: 127.0.0.1)
• HOUDI_LOCAL_API_PORT (default: 3210)
• HOUDI_LOCAL_API_TOKEN (opcional, exige Authorization: Bearer)
• HOUDI_INCOMING_QUEUE_MAX_PER_CHAT (default: 30, backpressure por chat)
• HOUDI_INCOMING_QUEUE_MAX_TOTAL (default: 400, backpressure global)
• HOUDI_HANDLER_TIMEOUT_MS (default: 45000, timeout por handler natural)
• HOUDI_HANDLER_CIRCUIT_BREAKER_FAILURES (default: 3, fallas para abrir circuito)
• HOUDI_HANDLER_CIRCUIT_BREAKER_OPEN_MS (default: 60000, tiempo de circuito abierto)
• HOUDI_TRANSIENT_RETRY_ATTEMPTS (default: 3, reintentos para errores transitorios)
• HOUDI_TRANSIENT_RETRY_BASE_MS (default: 400, base para backoff+jitter)
• SLACK_BOT_TOKEN (opcional, bridge Slack Socket Mode)
• SLACK_APP_TOKEN (opcional, xapp-..., requerido para Socket Mode)
• SLACK_BRIDGE_USER_ID (opcional, userId autorizado de Houdi; si falta usa el primer TELEGRAM_ALLOWED_USER_IDS)
• SLACK_ALLOWED_USER_IDS (opcional, CSV de user IDs de Slack autorizados)
• SLACK_ALLOWED_CHANNEL_IDS (opcional, CSV de channel IDs autorizados)
• SLACK_REQUIRE_MENTION_IN_CHANNELS (default: true, en canales solo responde con mención @app)
• SLACK_BRIDGE_TIMEOUT_MS (default: 90000)
• SLACK_BRIDGE_RETRY_COUNT (default: 2)
• SLACK_BRIDGE_RETRY_DELAY_MS (default: 500)
• SLACK_REPLY_CHUNK_MAX_CHARS (default: 3500)
• SLACK_ENABLE_STATUS_REACTIONS (default: true, usa reacciones ⏳✅❌)
• SLACK_ENABLE_FILE_SNIPPET_FALLBACK (default: true, sube respuesta larga como archivo)
• SLACK_SNIPPET_THRESHOLD_CHARS (default: 12000)
• SLACK_EVENT_DEDUPE_TTL_MS (default: 120000, evita duplicados)
• SLACK_SLASH_COMMAND (default: houdi)
• SLACK_SLASH_EPHEMERAL (default: true)
• WHATSAPP_BRIDGE_HOST (default: 0.0.0.0)
• WHATSAPP_BRIDGE_PORT (default: 3390)
• WHATSAPP_WEBHOOK_PATH (default: /webhook/whatsapp)
• WHATSAPP_VERIFY_TOKEN (requerido, token de verificación del webhook)
• WHATSAPP_ACCESS_TOKEN (requerido, token permanente Meta/WhatsApp Cloud API)
• WHATSAPP_GRAPH_API_VERSION (default: v22.0)
• WHATSAPP_APP_SECRET (opcional, valida X-Hub-Signature-256)
• WHATSAPP_BRIDGE_USER_ID (opcional, fallback: SLACK_BRIDGE_USER_ID o primer TELEGRAM_ALLOWED_USER_IDS)
• WHATSAPP_ALLOWED_FROM (opcional, CSV de números permitidos, * para todos)
• WHATSAPP_WEBHOOK_MAX_BYTES (default: 1000000)
• WHATSAPP_BRIDGE_TIMEOUT_MS (default: 90000)
• WHATSAPP_BRIDGE_RETRY_COUNT (default: 2)
• WHATSAPP_BRIDGE_RETRY_DELAY_MS (default: 500)
• WHATSAPP_REPLY_CHUNK_MAX_CHARS (default: 1400)
• WHATSAPP_EVENT_DEDUPE_TTL_MS (default: 120000)
• WHATSAPP_SEND_BRIDGE_ERRORS_TO_USER (default: true)
• ADMIN_APPROVAL_TTL_SECONDS (default: 300)
• AUDIT_LOG_PATH (default: ./houdi-audit.log)
• ENABLE_REBOOT_COMMAND (default: false)
• REBOOT_COMMAND (default: sudo -n /usr/bin/systemctl reboot)

Ejecutar

Modo desarrollo:

npm run dev

Build + run:

npm run build
npm start

Bridge Slack (opcional):

npm run slack:bridge

Persistir bridge Slack con systemd --user:

./scripts/install-systemd-user-slack-bridge.sh

Bridge WhatsApp (opcional):

npm run whatsapp:bridge

Persistir bridge WhatsApp con systemd --user:

./scripts/install-systemd-user-whatsapp-bridge.sh

Stack tecnológico (librerías clave)

• grammy: integración Telegram.
• openai: capacidades de IA (chat/audio/razonamiento operativo).
• zod: validación de contratos y estructura de datos.
• googleapis: integración Gmail.
• cheerio: parsing de contenido web.
• pdf-parse, mammoth, jszip: lectura de documentos (PDF/Office).
• @slack/bolt: bridge e integración Slack.
• Meta Graph API (HTTP): bridge de WhatsApp Cloud API (webhook + outbound).
• dotenv, typescript, tsx: configuración y toolchain de ejecución.

Nota de privacidad del repositorio

Este repositorio excluye datasets y utilidades experimentales derivadas de conversaciones reales (last20, audit-derived) para evitar publicar contexto operativo o datos de usuario.

Requisitos Slack (Socket Mode, inspirado en flujo OpenClaw):

1. Crear Slack App.
2. Activar Socket Mode.
3. Crear App Token (xapp-...) con scope connections:write.
4. Instalar app y obtener Bot Token (xoxb-...).
5. En Event Subscriptions, habilitar eventos bot:
   • app_mention
   • message.channels
   • message.groups
   • message.im
   • message.mpim
6. Invitar el bot a los canales donde quieras usarlo.

Scopes recomendados:

• Mínimos: app_mentions:read, channels:history, groups:history, im:history, mpim:history, chat:write
• Avanzados (robustez/capacidades): commands, reactions:write, files:write, users:read, channels:read, groups:read

Requisitos WhatsApp Cloud API:

1. Crear app en Meta for Developers y habilitar WhatsApp.
2. Configurar webhook con URL https://<tu-dominio>/<WHATSAPP_WEBHOOK_PATH>.
3. Definir Verify Token igual a WHATSAPP_VERIFY_TOKEN.
4. Generar token permanente y guardarlo en WHATSAPP_ACCESS_TOKEN.
5. (Recomendado) Definir WHATSAPP_APP_SECRET para validar firma HMAC.
6. Exponer el puerto del bridge (WHATSAPP_BRIDGE_PORT) vía Cloudflare Tunnel/Reverse proxy.

Importante: ejecuta solo una instancia del bot a la vez. Si intentas levantar otra, Houdi Agent lo bloqueará para evitar conflictos de Telegram polling.

Comandos (referencia con sintaxis Telegram)

Esta lista usa formato /comando porque Telegram es el canal principal de referencia. Las mismas capacidades se pueden ejecutar también por Slack, WhatsApp y CLI mediante lenguaje natural o sintaxis equivalente según integración.

• /status
• /health
• /doctor
• /usage [topN|reset]
• /model [show|list|set <modelo>|reset]
• /mode [show|list|set <modelo>|reset] (alias de /model)
• /eco on|off|status
• /domains
• /policy
• /agenticcanary [status|<0-100>]
• /agent
• /agent set <nombre>
• /ask <pregunta>
• /readfile <ruta> [previewChars]
• /askfile <ruta> <pregunta>
• /mkfile <ruta> [contenido]
• /files [limit]
• /getfile <ruta|n>
• /images [limit]
• /workspace ... (list, mkdir, touch, write, mv, rename, rm, send)
• /web <consulta>
• /webopen <n|url> [pregunta]
• /webask <consulta>
• /task ...
• /gmail ...
• /remember <nota>
• /memory
• /memory search <texto>
• /memory view <path> [from] [lines]
• /interests [status|add|del|clear|suggest]
• /suggest now|status
• /selfskill <instrucción>
• /selfskill list
• /selfskill del <n|last>
• /selfskill draft <start|add|show|apply|cancel>
• /selfrestart
• /selfupdate [check]
• /intentstats [n]
• /intentfit [n] [iter]
• /intentreload
• /intentroutes
• /intentcalibrate [n]
• /intentcurate [n] [apply]
• /intentab
• /intentversion [list|save [label]|rollback <id>]
• /intentcanary [status|set <id> <pct>|off]
• /safe on|off|status
• /shell <instrucción>
• /shellmode on|off
• /exec <comando> [args]
• /reboot (/reboot status)
• /adminmode (deprecado, usar /agent set <admin|operator>)
• /approvals
• /approve <id>
• /deny <id>
• /confirm <plan_id>
• /cancelplan <plan_id>
• /outbox [status|flush|recover]
• /metrics [reset]
• /panic on|off|status
• /task running
• /kill <taskId>

También puedes escribir mensajes normales (sin /) y el bot responderá con el proveedor IA configurado. Si detecta intención de web (buscar en internet o analizar una URL), lo hace en modo natural sin comandos. Si detecta intención de recordatorios/tareas con fecha/hora, las agenda en lenguaje natural. Si activas /shellmode on, esos mensajes también podrán disparar ejecución shell (siempre limitada por la allowlist del agente activo). También puedes enviar nota de voz/audio: el bot lo transcribe y responde sobre ese contenido. Si envías un archivo por Telegram (document), lo guarda automáticamente en workspace/files/. Si envías una imagen/foto, la guarda en workspace/images/ y además puede analizarla con IA multimodal. También puedes pedir en lenguaje natural operaciones sobre workspace (listar, crear carpeta, crear archivo simple, mover, renombrar, eliminar y enviar archivos). Para acciones sensibles (exec, send de Gmail y borrado en workspace), puede requerir Plan Preview y confirmación explícita con /confirm.

Seleccion de modelo IA por chat

Además del default global por .env (OPENAI_MODEL / ANTHROPIC_MODEL / GEMINI_MODEL), puedes cambiar el modelo en runtime para un chat específico:

• /model o /mode o /model show: muestra modelo actual del chat, default global y lista sugerida por costo.
• /model list: muestra solo la lista sugerida (menor -> mayor costo).
• /model set <modelo>: fija override por chat (ej. gpt-4o-mini, claude-3-5-sonnet-latest, gemini-2.0-flash).
• /model reset: vuelve al default de .env.

Notas:

• El override persiste en la base de estado (sobrevive reinicios), no modifica .env.
• Aplica a consultas IA de chat, analisis de imagen y planificacion de /shell.
• En /status, el bot informa proveedor detectado para el modelo activo del chat.

Modo ECO (ahorro de tokens)

• /eco status: muestra estado actual de ECO para el chat y su tope de salida.
• /eco on: habilita respuestas más compactas para ahorrar tokens.
• /eco off: vuelve al tope normal de salida.

Configuración relacionada:

• HOUDI_ECO_MODE_DEFAULT: valor inicial por chat (true/false) si el chat todavía no tiene override runtime.
• OPENAI_ECO_MAX_OUTPUT_TOKENS: tope de output tokens cuando ECO está activo.

Operación y robustez

• /health: salud runtime (cola, circuit-breakers, outbox, SQLite, workspace).
• /doctor: ejecuta chequeos rápidos de runtime, permisos, credenciales y seguridad base.
• /usage: muestra tokens/costo estimado IA acumulado desde que inició el proceso.
• /usage reset: reinicia contadores locales de uso IA.
• /metrics: snapshot de observabilidad (counters/timings/colas/outbox).
• /domains: lista dominios modulares activos (router/workspace/gmail) y sus capacidades.
• Estado runtime crítico persistente en SQLite: aprobaciones, planes pendientes, confirmaciones de borrado, panic mode y settings por chat (agente activo, shellmode, eco, safe y modelo IA).

CLI local

Además de Telegram, puedes consultar al agente desde terminal. Por defecto, la CLI usa --transport auto: si detecta bridge local activo, enruta al mismo pipeline natural de Telegram (paridad de funciones de texto). Si no hay bridge disponible, cae a modo local con el proveedor IA configurado.

One-shot:

npm run cli -- agent --message "te acordas de lo que hablamos de gmail"

Interactivo:

npm run cli -- chat
# o:
./scripts/houdi-cli.sh chat

Memoria por CLI:

npm run cli -- memory status
npm run cli -- memory view memory/2026-02-20.md 1 80
npm run cli -- remember "nota rápida desde CLI"

Opciones útiles:

• --chat-id <n>: scope de memoria por chat para continuidad.
• --user-id <n>: userId lógico para permisos/seguridad.
• --transport <auto|bridge|local>: auto (default), bridge (forzado), local (forzado).
• --json: salida JSON.
• --no-memory: consulta al modelo sin inyectar memoria.
• --no-remember: no persistir turnos en memoria.

Operaciones de Workspace

Comando opcional:

• /workspace o /workspace list [ruta]
• /workspace mkdir <ruta>
• /workspace touch <ruta> [contenido]
• /workspace write <ruta> <contenido>
• /workspace mv <origen> <destino>
• /workspace rename <origen> <destino>
• /workspace rm <ruta>
• /workspace send <ruta|n>
• /mkfile <ruta> [contenido]
• /getfile <ruta|n>

Modo natural:

• mostrame que hay en workspace
• crea carpeta reportes/2026
• mueve "files/chat-123/2026-02-19/reporte.pdf" a "archivados/reporte.pdf"
• renombra "archivados/reporte.pdf" a "archivados/reporte-final.pdf"
• elimina "archivados/reporte-final.pdf"
• crea archivo notas.txt
• crea archivo datos.csv con contenido: id,nombre\n1,Ana
• crea archivo config.json con contenido: {"modo":"demo"}
• enviame "files/chat-123/2026-02-19/reporte.pdf"
• enviame el archivo 2

Task y Recordatorios

Permite crear tareas programadas con lenguaje natural y dispararlas automáticamente en el chat.

Comandos:

• /task o /task list
• /task add <cuando> | <detalle>
• /task del <n|id|last>
• /task edit <n|id> | <nuevo cuando> | <nuevo detalle opcional>

Modo natural:

• recordame mañana a las 10 pagar expensas
• programa una tarea para el viernes 15:30 llamar a Juan
• crea un recordatorio en 2 horas para tomar agua
• lista mis tareas
• elimina la tarea 2
• edita la tarea 1 para pasado mañana 09:00

Auto-Mejora Controlada

Puedes sumar habilidades persistentes sin tocar código fuente manualmente:

• /selfskill <instrucción>: guarda una habilidad/regla en workspace/AGENTS.md (sección Dynamic Skills).
• /selfskill list: muestra las últimas habilidades agregadas.
• /selfskill del <n|last>: elimina una habilidad por índice (o la última).
• /selfskill draft ...: permite construir una habilidad en varios mensajes y aplicarla al final.
• /selfrestart: reinicia el servicio del agente respetando el perfil de seguridad activo.
• /selfupdate [check]: revisa o aplica actualización a la última versión del repo (git pull --ff-only, npm install si cambia package*.json, npm run build y reinicio).

Ejemplos:

• /selfskill Prioriza responder con formato checklist en tareas operativas
• /selfskill Cuando pida "último correo", leer directamente el mensaje más reciente

Modo natural (sin comandos):

• agrega la habilidad de responder siempre con pasos concretos
• suma la habilidad de confirmar el plan antes de ejecutar cambios
• crea la habilidad de mostrar siempre fuente al responder sobre web
• crear skill para priorizar respuestas breves y accionables
• nueva habilidad: cuando diga "último correo", leer directo el más reciente
• quiero crear una skill en varios mensajes
• agrega: responde con checklist
• agrega: prioriza acciones de alto impacto
• listo, crea la habilidad
• elimina la habilidad 2
• actualizate a la ultima version del repo
• reinicia el agente

Aprendizaje de Intereses y Sugerencias Proactivas

El agente aprende automaticamente por recurrencia en pedidos de noticias/novedades web y puede sugerir contenido reciente sin que lo pidas.

• Límite duro diario configurable (default: 15 sugerencias por día).
• Intervalo mínimo entre sugerencias configurable.
• Persistente en archivo (HOUDI_INTERESTS_FILE) para no perder aprendizaje al reiniciar.

Comandos útiles:

• /interests: ver perfil aprendido (observaciones, categorias y keywords top).
• /interests add <tema>: agregar interes manual para noticias.
• /interests del <keyword>: borrar un interes puntual.
• /interests clear: borrar todo el perfil de intereses del chat.
• /interests suggest: generar sugerencia inmediata de noticias recientes.
• /suggest status: ver cuota/config.
• /suggest now: forzar una sugerencia de prueba.

Integración Gmail (cuenta única)

Permite consultar y operar una cuenta Gmail conectada por OAuth2 (sin requerir Workspace).

Setup mínimo:

1. Crear credenciales OAuth en Google Cloud (Gmail API habilitada).
2. Obtener refresh_token del usuario (scope recomendado: gmail.readonly gmail.send gmail.modify https://www.googleapis.com/auth/gmail.compose).
   • Si la cuenta quedó con scopes acotados de metadata, el bot hace fallback automático para lectura (read/thread/draft read) y evita el error de formato FULL.
3. Completar en .env:
   • ENABLE_GMAIL_ACCOUNT=true
   • GMAIL_CLIENT_ID=...
   • GMAIL_CLIENT_SECRET=...
   • GMAIL_REFRESH_TOKEN=...
   • GMAIL_ACCOUNT_EMAIL=tu_cuenta@gmail.com (opcional)
4. Reiniciar el bot.

Rotación de credenciales (sin cambiar código):

1. Generar un nuevo refresh_token en Google OAuth con los scopes anteriores.
2. Reemplazar en .env: GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN.
3. Verificar con /gmail status y /gmail profile.
4. Si falla autenticación, revocar token viejo en Google Account Security y repetir paso 1.

Comandos:

• /gmail status
• /gmail profile
• /gmail list [query ...] [limit=10]
• /gmail read <messageId>
• /gmail send <to> "<subject>" "<body>" [cc=a@x.com,b@y.com] [bcc=z@x.com] [attach=./file.pdf,./otro.csv]
• /gmail reply <messageId> "<body>" [all=true] [cc=a@x.com] [bcc=b@x.com] [attach=./file.pdf]
• /gmail forward <messageId> <to> "<body>" [cc=a@x.com] [bcc=b@x.com] [attach=./file.pdf]
• /gmail thread <threadId> [limit=10]
• /gmail draft create <to> "<subject>" "<body>" [cc=a@x.com] [bcc=b@x.com] [attach=./file.pdf]
• /gmail draft list [limit=10]
• /gmail draft read <draftId>
• /gmail draft send <draftId>
• /gmail draft delete <draftId>
• /gmail markread <messageId>
• /gmail markunread <messageId>
• /gmail trash <messageId>
• /gmail untrash <messageId>
• /gmail star <messageId>
• /gmail unstar <messageId>
• /gmail recipients list
• /gmail recipients add "<nombre>" <email>
• /gmail recipients edit <nombre|n> [name="<nuevo nombre>"] [email=<nuevo@email>]
• /gmail recipients del <nombre|n>
• /gmail recipients clear

Modo natural (sin comandos):

• mostrame los ultimos correos no leídos
• lee el correo 2
• marcalo como leído
• enviá un correo a ana@empresa.com asunto: Reunión cuerpo: Confirmo mañana 10am
• agrega destinatario Ana ana@empresa.com
• actualiza destinatario Ana ana.nueva@empresa.com
• elimina destinatario Ana
• decime el estado de gmail
• mostrame el perfil de la cuenta gmail conectada

Nota de seguridad:

• El bot exige que el agente activo tenga gmail-api en allowCommands (incluido en operator y admin).
• En las respuestas, los IDs se muestran como #<valor> (además del valor crudo en `...`), sin prefijo id_.

Regla de activación:

• trae los ultimos 5 mensajes de Persona Ejemplo en linkedin profile_a

• En lenguaje natural, count por defecto es 5 (max 5).

• La lectura prioriza mensajes del prospecto (entrantes/no propios).

• El parser usa estrategia híbrida (reglas + fallback IA) para extraer first_name, last_name, fuente y reducir errores de interpretación en frases libres.

fuente se normaliza a account. Si necesitas alias personalizados usa:

Instalación de servicios systemd --user para dejarlo persistente:

cd /home/houdi/houdi-agent

El script crea:

Navegación Web

Comandos:

• /web <consulta>: busca en la web y devuelve resultados numerados.
• /weather [ubicación]: clima actual + próximos días (Open-Meteo).
• /webopen <n|url> [pregunta]: abre un resultado (o URL directa). Si agregas pregunta, lo analiza con IA.
• /webask <consulta>: búsqueda + síntesis automática con fuentes.

Ejemplos:

• /web precio dolar oficial argentina hoy
• /webopen 1 resumen en 5 puntos
• /webask cambios de Node.js v24

Modo natural:

• busca en internet cambios de Node.js v24
• busca precio bitcoin hoy
• dime noticias interesantes del mundo cripto
• contame últimas noticias de política argentina
• abre https://nodejs.org/en/blog y resumilo
• quiero links sobre ollama en docker

Para pedidos de noticias en lenguaje natural, el buscador prioriza lo más reciente y completa con fuentes web relevantes.

Lectura de Documentos (PDF + Office)

Comandos:

• /readfile <ruta> [previewChars]: extrae texto del archivo y muestra vista previa.
• /askfile <ruta> <pregunta>: extrae texto y consulta IA sobre ese documento.

Modo natural:

• Puedes escribir en chat libre o en /ask algo como: en workspace hay un contrato.pdf, analizalo
• Si detecta referencia a archivo + intención (leer/analizar/resumir), lo procesa sin comando explícito.

Formatos soportados:

• PDF: .pdf (via pdf-parse)
• Word: .docx (via mammoth)
• Presentaciones: .pptx, .odp (extracción XML)
• Texto OpenDocument: .odt
• Rich text: .rtf
• Texto plano: .txt, .md, .csv, .tsv, .json, .yml, .yaml, .xml, .html, .htm, etc.

Notas:

• Si la ruta tiene espacios, usa comillas: /readfile "Documentos/Reporte Q1 2026.pdf"
• Formatos legacy .doc y .ppt no están soportados directamente; conviene convertirlos a .docx/.pptx.
• Por seguridad, solo se leen archivos dentro del directorio del proyecto.

Memoria + Personalidad

Houdi ahora usa un workspace con archivos de contexto inyectados al prompt:

• AGENTS.md: lineamientos operativos
• SOUL.md: personalidad y tono
• USER.md: perfil y preferencias
• HEARTBEAT.md: checklist de heartbeat
• MEMORY.md: memoria de largo plazo
• memory/YYYY-MM-DD.md: memoria diaria

Comportamiento:

• El bot crea estos archivos automáticamente si faltan.
• Antes de responder, construye contexto con esos archivos (con límites de tamaño).
• Hace recall en memoria (MEMORY.md + memory/*.md) y pasa snippets relevantes al modelo.
• El recall usa backend híbrido (lexical + semántico + recencia + MMR) con fallback automático a scan.
• También inyecta memoria reciente (hoy/ayer) para continuidad aunque no hagas búsqueda explícita.
• Antes de construir contexto para IA, fuerza un flush de continuidad por chat para reducir pérdida en conversaciones largas.
• Guarda automáticamente intercambios de chat (usuario/asistente) en memory/YYYY-MM-DD.md.
• Mantiene memoria por chat en memory/chats/chat-<id>/YYYY-MM-DD.md y snapshot de continuidad en memory/chats/chat-<id>/CONTINUITY.md.
• Puedes guardar notas rápidas con /remember.
• En chat libre puedes preguntar: te acordás de ..., recordás ..., buscá en memoria sobre ....

Operación Segura por Agente

1. Mantén operator como modo normal (default). Es un perfil workspaceOnly con allowlist explícita para trabajo en archivos, web local y Gmail.

2. Cuando necesites privilegios altos, cambia temporalmente a admin:

/agent set admin

3. Para ejecuciones sensibles (/exec o shell IA), el bot crea una solicitud con ID.

4. Acepta o rechaza:

/approve <id>
/deny <id>

5. Si necesitas corte total:

/panic on

/panic on bloquea nuevas ejecuciones, limpia aprobaciones pendientes y mata tareas activas.

Reinicio Remoto Seguro

1. En .env, habilita:

ENABLE_REBOOT_COMMAND=true
REBOOT_COMMAND=sudo -n /usr/bin/systemctl reboot

2. Cambia temporalmente a admin para operar reboot con permisos elevados:

/agent set admin
/reboot
/approve <id>
/agent set operator

El bot nunca ejecuta /reboot directo: siempre genera aprobación primero.

Arranque Automático Tras Reinicio (Robusto, recomendado)

Usa servicio systemd de sistema (no --user), para que arranque al boot aunque no se abra sesión.

Instalar:

cd /home/houdi/houdi-agent
npm run build
sudo ./scripts/install-systemd-system-service.sh

Ver estado:

sudo systemctl status houdi-agent.service --no-pager

Ver logs:

sudo journalctl -u houdi-agent.service -f

La unidad se instala con Restart=on-failure (no always) y límites de reinicio para evitar bucles infinitos. Si necesitas ajustar política:

sudo RESTART_POLICY=on-failure RESTART_SEC=5 START_LIMIT_INTERVAL=60 START_LIMIT_BURST=5 ./scripts/install-systemd-system-service.sh

Para detenerlo sin relanzado:

sudo systemctl disable --now houdi-agent.service

Desinstalar:

cd /home/houdi/houdi-agent
sudo ./scripts/uninstall-systemd-system-service.sh

Arranque con systemd user (alternativa)

Solo recomendable si aceptas depender de sesión de usuario o de linger.

cd /home/houdi/houdi-agent
./scripts/install-systemd-user-service.sh
sudo loginctl enable-linger $USER

También usa Restart=on-failure con límites de reintentos.

Checklist Post-Reboot (30s)

Valida estado del servicio, instancia única y configuración clave:

cd /home/houdi/houdi-agent
./scripts/check-post-reboot.sh

Si devuelve FAIL, corrige antes de usar /reboot.

Export de Configuración Crítica (sin secretos)

Genera snapshot en backups/ con:

• unidad systemd visible por usuario
• .env sanitizado (TELEGRAM_BOT_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY y GEMINI_API_KEY redacted)
• perfiles de agentes
• manifiesto con checksums

cd /home/houdi/houdi-agent
./scripts/export-houdi-config.sh

También crea manual-root-backup.txt con comandos para respaldar archivos root-only.

Si deja de responder

1. Mata instancias duplicadas:

pkill -f "npm run dev" || true
pkill -f "node dist/index.js" || true

2. Inicia una sola:

npm run dev

Estructura

• src/index.ts: bot Telegram + comandos
• src/task-runner.ts: ejecución y tracking de tareas
• src/agents.ts: carga y validación de perfiles de agente
• agents/*.json: permisos por agente

Roadmap recomendado

1. Pairing explícito (en vez de allowlist fija)
2. Bitácora persistente de tareas (SQLite)
3. Políticas por chat/agent (RBAC)
4. Cola de trabajos y workers separados
5. Plugin system para acciones (archivos, browser, RDP, etc.)

Contacto operativo: houdi@houdiagent.com