Ejemplo práctico: El bot de actualización automática de StageX
stagehand es un bot de ZeroClaw en producción. Supervisa el feed de versiones del proyecto upstream, actualiza la versión de un paquete de StageX, lo compila, verifica que se reproduce por digest, sube el cambio, abre un borrador de pull request y anuncia el resultado. Ningún humano interviene hasta que existe el PR.
Es la implementación SOP de referencia: la canalización es un SOP determinista, el feed de release llega a través de un canal AMQP, y el agente ejecuta el SOP con la herramienta sop_execute. AMQP también puede impulsar directamente el motor SOP como un fan-in en vivo; este ejemplo usa por elección el patrón de que el agente lo ejecuta, donde el canal lleva cada release al bucle del agente y el agente inicia la ejecución. Esa separación es lo que hace que el patrón sea reutilizable.
Cada comando, clave de configuración, nombre de herramienta, valor de estado y clave de auditoría a continuación corresponde a una definición concreta en el código base.
1. La compilación
stagehand necesita que los canales AMQP y Matrix estén compilados. Ambos están condicionados por features y desactivados de forma predeterminada.
sh
cargo build --release --features channel-amqp,channel-matrix
El resultado es un binario zeroclaw que carga los tipos de canal amqp y matrix. Un binario compilado sin channel-amqp rechaza un bloque de canal amqp al inicio y registra una advertencia en lugar de cargarlo.
2. Los Artefactos
Tres elementos residen bajo la raíz de instalación de ZeroClaw:
| Artefacto | Ubicación | Rol |
|---|---|---|
| Configuración de ZeroClaw | ~/.zeroclaw/ | El agente, los canales AMQP + Matrix y la configuración de sop. |
sops/stagex-update/ | <install>/shared/sops/stagex-update/ | El pipeline: SOP.toml (metadatos) + SOP.md (los ocho pasos). |
skills/stagex-update/ | <install>/shared/skills/stagex-update/ | El pegamento que activa el SOP en un evento de lanzamiento. |
La configuración conecta el agente a dos canales (amqp.anitya, matrix.announce), lo ejecuta con autonomía total de modo que confirma los cambios, los envía y abre el PR sin ninguna validación previa, y apunta [sop] a shared/sops en modo de ejecución deterministic. El agente nunca fusiona; un mantenedor adopta la rama y fusiona mediante un commit firmado.
El canal AMQP
El canal amqp.anitya consume el feed público de Fedora Messaging. Vincula la clave de enrutamiento de actualización de versión de Anitya en el exchange amq.topic y se conecta mediante amqps:// con TLS mutuo de cliente; el broker de Fedora requiere un certificado de cliente, por lo que el canal presenta los client_cert y client_key configurados. El canal valida su configuración al cargarse: amqp_url debe usar amqp:// o amqps://, una URL amqps:// requiere ca_cert, client_cert y client_key deben proporcionarse juntos, el exchange no debe estar vacío y debe vincularse al menos una clave de enrutamiento.
El cuerpo JSON de cada entrega se mapea al mensaje entrante del agente mediante content_template, cuyos marcadores de posición {dotted.path} se resuelven contra el cuerpo, convirtiendo una entrega de release en “New release: bzip2 1.0.9 (was 1.0.8). Bump the StageX package for bzip2.” La ruta con puntos thread_id_field correlaciona las respuestas con el evento de origen. La entrega es al menos una vez por defecto (durable_ack = true): el canal confirma un release solo después de que se haya entregado de forma duradera al bucle del agente, de modo que un fallo antes de que comience la ejecución reenvía el evento en lugar de descartarlo silenciosamente. Esto es importante para un pipeline desatendido con efectos secundarios; un release perdido dejaría un paquete silenciosamente rezagado. Las credenciales y los certificados se suministran en el momento del despliegue y nunca se confirman en el repositorio: el token de push de Codeberg es una variable de entorno que lee el shell del agente, el token de acceso de Matrix se configura en la instancia en ejecución, y los certificados de CA y de cliente de Fedora se colocan en el host.
3. Validación
La superficie de zeroclaw sop consta de tres subcomandos. No existe un subcomando run; las ejecuciones se inician desde un disparador o desde la herramienta sop_execute.
sh
zeroclaw sop list
zeroclaw sop validate stagex-update
zeroclaw sop show stagex-update
La validación muestra advertencias por un nombre o descripción vacíos, ausencia de disparadores, ausencia de pasos (un SOP.md faltante o vacío) y saltos en la numeración de pasos. Una advertencia de pasos faltantes significa que la ejecución fallaría en tiempo de ejecución. Ejecute las mismas comprobaciones desde la interfaz de terminal de zerocode al iterar; la CLI es la comprobación reproducible en el momento del despliegue.
4. Despliegue
El bot se ejecuta como un daemon de larga duración para mantenerse conectado al broker y a la sala de Matrix.
sh
zeroclaw daemon
En un host siempre activo se ejecuta como un servicio administrado que se reinicia con la máquina (consulte Servicio y demonio):
sh
zeroclaw service install
zeroclaw service start
El canal AMQP se conecta al broker, vincula su clave de enrutamiento y consume las entregas. El bot permanece inactivo hasta que upstream publica una versión.
5. Una release fluye a través
Anitya publica una entrega de actualización de versión. El canal AMQP la recibe, aplica el content_template y entrega al agente un mensaje entrante que indica el paquete, la nueva versión y la versión anterior. El agente dispara el pipeline:
// tool: sop_execute
// args: { "name": "stagex-update", "payload": "{\"project\":{\"name\":\"bzip2\"},\"version\":\"1.0.9\",\"old_version\":\"1.0.8\"}" }
sop_execute inicia un SopRun con un disparador manual y reenvía el payload al contexto de la ejecución. El ciclo de vida a partir de aquí es idéntico al de cualquier otra ejecución; la fuente del disparador es lo único que difiere.
6. La ejecución
Debido a que [sop] se ejecuta en modo deterministic, los pasos se ejecutan secuencialmente sin viajes de ida y vuelta al LLM entre ellos. La salida de cada paso se canaliza al siguiente, y solo el paso de obtención del parche llama al modelo, que es local, por lo que el código fuente del paquete nunca sale del host. Un paso de checkpoint se pausa para la aprobación humana; este pipeline se ejecuta de principio a fin hasta el borrador de PR.
running → completed
Los ocho pasos, analizados desde la sección ## Steps del SOP:
| # | Paso | Qué hace | Herramientas |
|---|---|---|---|
| 1 | Resolver | Asigne el proyecto upstream al paquete real de StageX; lea la versión actual; deténgase si no es estrictamente más reciente. | shell, file_read |
| 2 | Incremento de versión + hash | Establece la nueva versión, ejecuta make fetch, escribe el hash de origen correcto y vuelve a hacer fetch hasta que quede limpio. | shell, file_write |
| 3 | Compilar | Compila solo este paquete; reintenta una vez si hay un fallo de hash. | shell |
| 4 | Aplicar parche si está roto | Ante una falla de compilación, actualiza o aplica un parche usando el modelo local; marca las rupturas genuinas de API. | shell, file_read, file_write, http_request |
| 5 | Reproducción del digest | make digests, compila una segunda vez, confirma que el digest no ha cambiado. | shell |
| 6 | Confirmar + enviar | Haz commit en una rama por paquete y por versión; haz push al fork. | shell, git_operations |
| 7 | Abrir PR en borrador | Completa la plantilla de PR, adjunta los digests y márcalo como listo solo con una compilación reproducida limpia. | http_request |
| 8 | Anunciar | Publica el resultado en la sala de Matrix: paquete, delta de versión, estado de reproducción, digest, URL del PR. | shell |
El agente finaliza cada paso con una llamada a sop_advance que informa el resultado:
// tool: sop_advance
// args: { "run_id": "<run-id>", "status": "completed", "output": "Se actualizó bzip2 1.0.8 → 1.0.9; el hash del código fuente se volvió a derivar y se verificó." }
status es uno de completed, failed o skipped. Cuando se avanza el paso final, la ejecución pasa a completed y se establece su marca de tiempo completed_at.
El progreso es visible desde un turno del agente en cualquier momento:
// tool: sop_status
// args: { "sop_name": "stagex-update", "include_metrics": true }
Seguridad en modo headless
Cuando llega una entrega sin ningún bucle de agente activo que impulse los pasos, el runtime registra la ejecución y deja constancia en el log de cada acción pendiente en lugar de descartar el trabajo silenciosamente. La ejecución espera a que un turno de agente la haga avanzar.
7. El registro de auditoría
SopAuditLogger persiste cada transición en el backend de Memory configurado bajo la categoría sop. Una ejecución de actualización deja estas claves:
| Clave | Contenido |
|---|---|
sop_run_<run-id> | Instantánea completa de la ejecución, escrita al inicio y actualizada al finalizar. |
sop_step_<run-id>_1 … _8 | Un resultado por paso: estado, salida, marcas de tiempo. |
sop_approval_<run-id>_<step> | Un registro de aprobación del operador, cuando un paso de punto de control lo requiere. |
sop_timeout_approve_<run-id>_<step> | Un registro de aprobación automática por tiempo de espera agotado, cuando la aprobación de un punto de control supera el tiempo de espera. |
include_metrics: true en sop_status agrega agregados específicos de SOP; include_gate_status: true agrega el estado de fase de confianza y del evaluador de puertas. Estos se obtienen a través de sop_status, no de Prometheus. El endpoint /metrics, cuando el backend de observabilidad es prometheus, expone únicamente las familias generales zeroclaw_*.
8. Las Garantías
Cada garantía se rastrea hasta el pipeline:
- El código fuente nunca sale del host. El paso de obtención de parches se ejecuta contra un modelo local, por lo que el código fuente del paquete nunca llega a un proveedor remoto.
- La compilación se demuestra a sí misma. El paso 5 compila dos veces y compara los digests; el PR se marca como listo solo cuando ambos coinciden.
- Un humano es responsable del merge. El bot se detiene en “draft PR abierto”; un mantenedor adopta la rama y hace merge mediante un commit firmado. Nunca hace merge automáticamente.
- La ejecución es reconstruible. La instantánea de la ejecución y el resultado de cada paso se persisten bajo la categoría
sop, indexados por el ID de la ejecución.
9. El patrón
Un canal de entrada ingiere un evento, el agente activa un SOP con sop_execute y una pipeline determinista realiza el trabajo. Sustituye el feed AMQP por cualquier canal y los pasos por cualquier procedimiento, y el ciclo de vida, las puertas de aprobación y las claves de auditoría son idénticos. Cuando un paso requiere juicio humano, márcalo como checkpoint y la ejecución se pausa a la espera de una aprobación antes de continuar; la única diferencia con respecto a la ruta desatendida es quién hace avanzar la ejecución.