Añadir compatibilidad con Herdr a tu agente

Si desarrollas un agente de programación, puedes hacer que Herdr lo trate como uno más desde tu propio código. No hace falta abrir un pull request en Herdr ni esperar a una nueva versión.

En cuanto tu agente informa a Herdr, los usuarios tienen:

• el nombre de tu agente y su estado (en espera, trabajando o bloqueado) en la barra lateral y en herdr agent list
• notificaciones cuando termina o necesita que alguien decida
• herdr agent wait y el resto de automatizaciones que esperan a un estado del agente
• la misma sesión en el mismo panel después de reiniciar el servidor de Herdr

Herdr se encarga de las integraciones de los agentes cuyos fabricantes no publican una propia. Si mantienes tu agente, llevar tú la integración te permite corregirla al ritmo de tus propias versiones.

Cómo funciona

Todos los procesos de un panel de Herdr heredan estas variables de entorno:

Variable	Significado
HERDR_ENV	1 dentro de Herdr
HERDR_PANE_ID	El panel en el que corre tu agente
HERDR_BIN_PATH	El binario de Herdr al que pertenece el panel
HERDR_SOCKET_PATH	El socket de la API de Herdr

Tu agente envía tres tipos de informes a través de "$HERDR_BIN_PATH":

1. Estado. Informa de idle, working o blocked cada vez que cambie.
2. Comando de reanudación. Informa del comando que vuelve a abrir la sesión actual.
3. Liberación. Libera el panel cuando tu agente termine.

Informa solo cuando HERDR_ENV=1 y el resto de variables estén definidas. Fuera de Herdr, la integración no debe hacer nada.

Informar del estado

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --state working \
  --seq 1

• Informa de working cuando empiece un turno, de idle cuando tu agente esté listo para recibir instrucciones y de blocked cuando necesite que el usuario decida algo. Añade --message para explicar el bloqueo.
• --agent es el nombre que ven los usuarios. Usa el de tu agente, no el de un agente que Herdr ya admita.
• --source identifica tu integración. Mantenlo estable y único. No lo empieces por herdr:, porque ese prefijo lo usan las integraciones de Herdr.
• --seq es opcional, pero recomendable. Tiene que crecer con cada informe de tu fuente, también entre sesiones y reinicios de tu agente. Una marca de tiempo sirve bien. Herdr ignora los informes cuyo número no supere al último que aceptó, así que un informe tardío o desordenado no puede pisar un estado más reciente.

Para cambiar cómo aparece tu agente sin tocar su estado, por ejemplo con un título o un texto de estado propio, consulta Etiquetas personalizadas de estado.

Informar del comando de reanudación

Pon después de -- el comando que reanuda la sesión actual. Incluye las opciones que necesite esa sesión, como el modelo o el modo de permisos, para que la sesión reanudada se comporte igual:

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --state idle \
  --seq 2 \
  --agent-session-id "$SESSION_ID" \
  -- my-agent --resume "$SESSION_ID" --model my-model

Puedes adjuntar el comando a cualquier informe de estado o enviarlo con pane report-agent-session cuando solo cambie la sesión. Vuelve a informar de él cada vez que tu agente cambie de sesión.

Después de reiniciar el servidor de Herdr, Herdr abre el panel en el mismo directorio y ejecuta allí ese comando. El comando tiene que cumplir estas reglas:

• La primera palabra es un nombre de comando a secas que esté en el PATH del usuario, como my-agent, no una ruta.
• Ningún argumento contiene un apóstrofo ni un carácter de control.
• Como mucho 64 argumentos y 8 KiB en total.
• Tu fuente tiene que tener antes el panel, así que envía un informe de estado con report-agent antes del comando o junto a él. Si no, Herdr responde con resume_not_accepted.

Si el comando incumple alguna de las tres primeras reglas, Herdr lo rechaza con invalid_resume_argv y no aplica ese informe. Los usuarios pueden desactivar la reanudación con [session] resume_agents_on_restore = false.

Liberar el panel al salir

"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --seq 3

Al liberar el panel se borran en el acto el nombre, el estado y el comando de reanudación de tu agente. Libéralo solo cuando el usuario salga de verdad. Si tu agente sustituye una sesión por otra dentro del mismo proceso, informa de la sesión nueva en lugar de liberar el panel.

Si tu agente termina sin liberarlo, Herdr se da cuenta en cuanto el panel vuelve al prompt de la shell en reposo y borra el agente y su comando de reanudación. Suele tardar uno o dos segundos. Es una red de seguridad, no sustituye a la liberación.

Que no estorbe

• No dejes que Herdr ralentice tu agente. Envía los informes en segundo plano o con un tiempo de espera corto, e ignora los fallos.
• Envía solo el estado más reciente. Si se acumulan varios cambios mientras hay un informe en curso, descarta los antiguos.
• Los comandos de reanudación necesitan Herdr 0.9.2 o posterior. Las versiones anteriores los ignoran, así que en ellas los informes de estado y la liberación siguen funcionando.

Usar el socket directamente

HERDR_BIN_PATH y la CLI son la opción portable, también en Windows. Si tu agente necesita IPC directo, envía las peticiones equivalentes pane.report_agent, pane.report_agent_session y pane.release_agent que se describen en la API de socket. El comando de reanudación va en el array resume_argv.

Comprobar la integración

Arranca tu agente en un panel de Herdr y mira qué ve Herdr:

herdr pane get "$HERDR_PANE_ID"
herdr agent list

Para probar la restauración sin tocar tu sesión habitual, usa una sesión con nombre aparte:

1. Arranca herdr --session my-agent-test y ejecuta tu agente en un panel.
2. Detén esa sesión con herdr session stop my-agent-test.
3. Vuelve a arrancar herdr --session my-agent-test. El panel debería ejecutar tu comando de reanudación y tu agente debería volver a informar.