Agent Alerts Setup (AndreasInk/AgentAlertsSkill)

Configuración de Alertas del Agente

Diseña la automatización, configura el webhook alojado y entrega las ejecuciones en tiempo de ejecución a $agent-alerts-execution. No envíes durante la configuración a menos que el usuario solicite una prueba de humo.

Comienza Aquí

Abre o dirige al usuario a:

https://www.andreas.ink/agent

Sigue el flujo de conexión actual de la página con Agent Alerts en iPhone. Se crea un token solo de publicación para el tiempo de ejecución. No le pidas al usuario que pegue ese token en el chat.

Configura el Webhook

1. Nombra el tiempo de ejecución y completa el flujo de conexión en la página pública de configuración.
2. Elige la ubicación del token para el tiempo de ejecución:
   • Tiempo de ejecución alojado: almacena el token de un solo uso en el gestor de secretos de ese tiempo de ejecución como AGENTALERTS_AGENT_TOKEN.
   • Mac local: almacena exactamente una línea, AGENTALERTS_AGENT_TOKEN=<token>, en el archivo ~/.config/agent-alerts/token.env aprobado por el usuario y establece su modo en 0600.
3. Haz que el usuario ingrese el token directamente en el almacén de secretos seleccionado, fuera de la conversación con la IA. Nunca le pidas que lo pegue en el chat del agente.
4. Usa el endpoint integrado en ../agent-alerts-execution/scripts/send_webhook.sh. Establece AGENTALERTS_WEBHOOK_URL solo cuando la página de configuración proporcione un endpoint HTTPS diferente.
5. Permite HTTPS saliente solo a ese endpoint.
6. Autoriza la ruta absoluta exacta a send_webhook.sh para ejecuciones sin supervisión. No otorgues acceso amplio al shell.

Nunca coloques el token en un prompt, URL, cadena de consulta, registro, archivo fuente, archivo de configuración rastreado, historial de shell o argumento de comando.

Prepara y Valida una Prueba

Copia ../agent-alerts-execution/assets/compact-webhook-payload.json a un archivo de payload escribible y reemplaza sus valores de ejemplo. Usa una clave de idempotencia estable y única para el evento.

Valida el payload:

../agent-alerts-execution/scripts/send_webhook.sh --check payload.json

Valida el payload, la fuente del token, los permisos y el endpoint sin enviar:

../agent-alerts-execution/scripts/send_webhook.sh --check-config payload.json

Luego envía una prueba de humo no sensible:

../agent-alerts-execution/scripts/send_webhook.sh payload.json

Para una automatización sin supervisión, repite --check-config y el envío de prueba de humo desde el ejecutor guardado real. Ambos deben completarse sin un prompt de aprobación. Si el runner no puede ejecutar el helper exacto o alcanzar el endpoint, detente con AGENTALERTS_SCRIPT_NOT_AUTHORIZED.

Diseña la Alerta

Define:

1. Señal, fuente de datos y disparador.
2. Mapeos de good, warning y critical.
3. Condiciones de salto, horas de silencio y exclusiones.
4. Un activity_id estable o identificador de notificación.
5. Superficies: live_activity, widget y/o notification.
6. Texto de acción y una URL segura de destino o enlace profundo de la aplicación.
7. Un programador duradero cuando la alerta se ejecute más tarde o de forma repetida.

Agent Alerts entrega actualizaciones; no mantiene una sesión de agente activa. Una ejecución futura o recurrente está incompleta hasta que el programador permanezca registrado después de que la sesión actual se cierre. De lo contrario, devuelve AGENTALERTS_SCHEDULER_NOT_DURABLE.

Contrato del Payload

Usa el cuerpo compacto del webhook para alertas ordinarias:

{
  "title": "Compilación finalizada",
  "summary": "Todas las pruebas pasaron.",
  "status": "good",
  "activity_id": "build-monitor",
  "source_name": "Codex",
  "surfaces": ["live_activity", "notification"],
  "idempotency_key": "build-monitor-2026-07-29T18-30-00Z"
}

El webhook requiere:

Authorization: Bearer <AGENTALERTS_AGENT_TOKEN>
Content-Type: application/json
Idempotency-Key: <mismo valor que idempotency_key>

El helper proporciona estos encabezados sin exponer el token en los argumentos del proceso. Siempre usa el helper; no recrees la solicitud manualmente.

Los envíos compactos por defecto crean una actividad upsertada llamada webhook, entrega de producción y live_activity más notification cuando esos campos se omiten. Establécelos explícitamente cuando la automatización necesite un resultado diferente.

Para widgets, estado de Control Widget, diseños de builder u otros campos avanzados, usa el contrato completo del webhook en snake_case con un objeto payload anidado. No mezcles un objeto payload completo con campos compactos title, summary, status, source_name o deep_link.

Reglas de Copia y Entrega

Mantén la copia visible completa y dentro de estos límites:

Campo	Máximo de caracteres
source_name	14
title	32
summary	96

No confíes en el truncamiento ni agregues puntos suspensivos.

• live_activity actualiza la Dynamic Island o la pantalla de bloqueo.
• widget necesita su identificador de widget, una pequeña instantánea no secreta y recarga habilitada.
• notification necesita un identificador de hilo estable para agrupar.
• El estado de Control Widget debe ser verdadero para estados activos de advertencia o críticos y falso para estados claros o resueltos.

Entrega en Tiempo de Ejecución

Escribe una instrucción exacta de tiempo de ejecución:

Usa $agent-alerts-execution. Evalúa primero la condición de salto configurada.
Si es necesario enviar, escribe el JSON de Agent Alerts preparado en la ruta
del payload aprobada, luego invoca la ruta autorizada de send_webhook.sh con
esa archivo. Lee el token solo de AGENTALERTS_AGENT_TOKEN o del archivo
token.env aprobado. Reporta el estado devuelto y el destino, los conteos de
éxito y fallo sin imprimir secretos.

La configuración está completa solo cuando el runner real valida la configuración y envía sin interacción, el cronograma es duradero cuando se requiere, y el resultado se reporta sin exagerar la entrega visible en el dispositivo.