Ciclo de vida del trabajo en segundo plano
ZeroClaw tiene varias formas de continuar el trabajo después de la solicitud entrante que lo inició. Los trabajos cron, las ejecuciones de SOP, las tareas delegadas y los subagentes generados en tiempo de ejecución comparten cierta maquinaria de ejecución, pero no comparten un ciclo de vida ni un almacén duradero. El modo objetivo define un contrato de destino relacionado que aún no está conectado de extremo a extremo.
Utiliza esta página cuando un cambio añada trabajo programado o autónomo, introduzca un estado de espera o aprobación, modifique el comportamiento de cancelación o reinicio, o conecte trabajo secundario con una tarea propietaria. La primera pregunta de diseño no es «¿cómo se ejecuta en segundo plano?», sino «¿qué subsistema posee su ciclo de vida?».
Mapa de propiedad
| Tipo de trabajo | Propietario actual o superficie de estado | Registros duraderos |
|---|---|---|
| Tarea cron | Programador de Cron y almacenamiento | data/cron/jobs.db |
| Ejecución de SOP | SopEngine y SopRunStore | Memoria de proceso por defecto; data/sop/runs.db cuando la inicialización duradera de SQLite tiene éxito |
| Delegación en segundo plano | API de resultados de delegación, con anulaciones de supervisión del plano de control cuando estén disponibles | <workspace>/delegate_results/<task-id>.json; una fila de tarea de mejor esfuerzo en data/control_plane.db bajo un demonio iniciado |
| Subagente generado en tiempo de ejecución | Generar sitio, con supervisión del plano de control cuando esté disponible | Una fila de tarea de mejor esfuerzo en data/control_plane.db bajo un daemon iniciado |
Los metadatos duraderos no son lo mismo que la ejecución duradera. Un archivo de resultados o una fila de tarea puede conservar lo que se sabía y permitir que la recuperación marque el trabajo como perdido, agotado por tiempo de espera o terminal, sin conservar el futuro local al proceso que estaba realizando el trabajo.
Trabajos cron
Cron combina la pertenencia declarativa con un almacén de ejecución SQLite. Tanto las tareas creadas en tiempo de ejecución como las tareas de configuración reconciliadas llevan un agent_alias propietario; la ejecución resuelve la política de seguridad de ese agente en lugar de ejecutarse con una identidad de daemon del entorno.
El planificador sondea filas vencidas, habilitadas y sin reclamar. Reclamar una fila evita la selección duplicada mientras está en curso. La finalización registra una salida acotada y luego reprograma un trabajo recurrente, elimina un trabajo único de eliminación automática exitoso o deshabilita otro trabajo único. Si el proceso termina antes de liberar una reclamación, el siguiente inicio del planificador limpia el bloqueo obsoleto.
El comportamiento de inicio es explícito. Con catch-up habilitado, los trabajos vencidos se consideran para su ejecución. De lo contrario, un one-shot vencido se deshabilita con un resultado skipped, mientras que un trabajo recurrente avanza a su siguiente aparición futura sin registrar un resultado de ejecución. El planificador comprueba su token de cancelación entre iteraciones de sondeo, por lo que el apagado espera a que termine el lote actual de trabajos vencidos antes de que el bucle finalice. Cancelar el planificador no es una garantía de que un efecto secundario externo ya despachado pueda revertirse.
ejecuciones de SOP
Las definiciones de SOP se encuentran en el directorio sops configurado. SopEngine gestiona el avance de las ejecuciones, las esperas de aprobación, los puntos de control, las transiciones terminales y la superficie de estado en proceso. SopRunStore es la fuente de verdad de la concurrencia cuando admite y reclama una ejecución.
La persistencia de ejecuciones es opcional. Con el valor predeterminado sop.persist_runs = false, el motor utiliza un almacén en memoria. Cuando la persistencia está habilitada, el backend SQLite predeterminado escribe runs.db en <data_dir>/sop a menos que run_state_dir lo reemplace. Una inicialización correcta del almacén permite que las instantáneas activas, los registros terminales, los eventos, las revisiones y las reclamaciones de concurrencia admitan la restauración tras un reinicio. Si la inicialización del almacén falla, el daemon registra una advertencia y recurre al almacén en memoria.
Los registros de auditoría SOP en el backend de Memory son una superficie de observabilidad independiente. No reemplazan el almacén de ejecuciones y no deben usarse como autoridad para determinar si una ejecución está activa, en pausa, aprobada o en estado terminal.
Los estados de aprobación y de punto de control son estados de control duraderos únicamente cuando el almacén de ejecuciones es duradero. La política de tiempo de espera permanece fail-closed de forma predeterminada: una aprobación que ha excedido el tiempo de espera se escala y sigue esperando, a menos que la configuración seleccione explícitamente la cancelación o el comportamiento heredado de auto-aprobación.
Delegación y subagentes
Los subagentes heredan el límite de seguridad efectivo de su elemento padre. Las anulaciones de política y de memoria pueden reducir el ámbito del padre, pero no ampliarlo, y la contabilización de acciones del hijo utiliza el rastreador del padre, de modo que la creación de hijos no puede eludir el presupuesto de acciones del padre.
La ruta de spawn_subagent es síncrona: el proceso padre espera a que finalice la ejecución del hijo, y esta ruta no tiene un tiempo de espera local ni un manejador de cancelación en segundo plano.
La herramienta delegate puede ejecutarse de forma síncrona o iniciar una tarea en segundo plano y devolver un UUID. Los resultados en segundo plano se escriben de forma atómica en el workspace pasado a la herramienta y pueden consultarse, listarse, esperarse en lote o cancelarse. Un registro de cancelación en vivo asigna los ID de las tareas a tokens locales del proceso; la cancelación actualiza el resultado persistido y señaliza la tarea en ejecución cuando ese token en vivo sigue estando disponible.
Bajo un daemon iniciado, los productores de delegados y subagentes también escriben filas de tareas en el plano de control duradero. Estas escrituras son de mejor esfuerzo e independientes de las escrituras de archivos de resultados de delegados. Las lecturas de resultados de delegados siguen siendo archivo primero; solo un archivo aún marcado como running se superpone como lost o timed_out desde el estado del plano de control, por lo que los dos registros pueden divergir.
Las filas actuales de delegados y subagentes rellenan agente, estado, PID del propietario e ID de arranque, profundidad y marcas de tiempo. Dejan ausentes la señal de vida, la tarea principal, la ruta y el principal. La recuperación al iniciar marca como lost las filas en ejecución de arranques anteriores; timed_out se aplica solo a productores que emiten señales de vida obsoletas, cosa que estos productores no hacen actualmente. La fila de tarea hace visible un elemento secundario interrumpido, pero no recrea su ejecución.
Contrato de destino en modo objetivo
ADR-008 acepta el plano de control de tareas como la autoridad futura para el ciclo de vida de objetivos, la propiedad, la ruta, el principal, la relación con el padre y la elegibilidad de recuperación. El repositorio contiene almacenamiento de objetivos y APIs del plano de control, pero la admisión y ejecución de objetivos en producción aún no están conectadas de extremo a extremo.
Una ruta en segundo plano puede participar en el modo de objetivo solo después de conservar la relación con el objetivo propietario e informarle el estado terminal y el uso del modelo. Hasta entonces, esa ruta es trabajo ordinario en segundo plano en lugar de ejecución en modo de objetivo.
Lista de verificación de cambios
Para los cambios de trabajo en segundo plano, responde estas preguntas antes de que el revisor apruebe:
- ¿Qué subsistema controla el ciclo de vida y qué almacén es el autoritativo?
- ¿El proceso de trabajo es local, tiene supervisión duradera o realmente puede reanudarse tras un reinicio?
- ¿Qué token o acción del plano de control lo cancela, y qué puede quedar en tránsito?
- ¿Qué campos de tarea padre, agente, ruta, principal, profundidad de recursión y uso puebla realmente esta ruta?
- ¿Se pueden distinguir los estados de espera, aprobación, punto de control, perdido, tiempo de espera agotado y terminal?
- ¿Puede la recuperación al inicio duplicar un efecto secundario o dejar un reclamo bloqueado silenciosamente?
- ¿La entrega de resultados sigue siendo idempotente si se observa la finalización después de un reinicio?
Punteros de origen
- Planificador cron y persistencia:
crates/zeroclaw-runtime/src/cron/scheduler.rs,crates/zeroclaw-runtime/src/cron/store.rs - Motor SOP y almacenes de ejecución:
crates/zeroclaw-runtime/src/sop/engine.rs,crates/zeroclaw-runtime/src/sop/store/ - Delegación y comportamiento de los subagentes: Delegación y subagentes,
crates/zeroclaw-runtime/src/tools/delegate.rs,crates/zeroclaw-runtime/src/tools/spawn_subagent.rs,crates/zeroclaw-runtime/src/subagent/mod.rs - Plano de control de tareas persistentes y recuperación:
crates/zeroclaw-runtime/src/control_plane/ - Decisión del modo de objetivos: ADR-008
- Guía del operador de SOP: Cómo funcionan los SOP