Cycle de vie du travail en arrière-plan

ZeroClaw dispose de plusieurs façons de poursuivre le travail après la requête entrante qui l’a démarré. Les tâches cron, les exécutions SOP, les tâches déléguées et les sous-agents instanciés à l’exécution partagent certains mécanismes d’exécution, mais ils ne partagent ni un cycle de vie unique ni un store durable unique. Le mode objectif définit un contrat cible associé qui n’est pas encore connecté de bout en bout.

Utilisez cette page lorsqu’une modification ajoute un travail planifié ou autonome, introduit un état d’attente ou d’approbation, modifie le comportement d’annulation ou de redémarrage, ou relie un travail enfant à une tâche propriétaire. La première question de conception n’est pas « comment cela s’exécute-t-il en arrière-plan ? » mais « quel sous-système est propriétaire de son cycle de vie ? »

Carte des propriétés

Les métadonnées durables ne sont pas la même chose que l’exécution durable. Un fichier de résultat ou une ligne de tâche peut préserver ce qui était connu et permettre à la récupération de marquer le travail comme perdu, expiré ou terminal sans préserver le futur local au processus qui effectuait ce travail.

tâches Cron

Cron combine l’appartenance déclarative avec un magasin d’exécution SQLite. Les jobs créés au moment de l’exécution et les jobs de configuration réconciliés portent tous un agent_alias propriétaire ; l’exécution résout la politique de sécurité de cet agent au lieu de s’exécuter sous une identité de démon ambiante.

Le planificateur interroge les lignes échues, activées et non réservées. La réservation d’une ligne empêche une sélection en double pendant son traitement. La finalisation enregistre une sortie limitée, puis reprogramme une tâche récurrente, supprime une tâche ponctuelle à suppression automatique réussie, ou désactive une autre tâche ponctuelle. Si le processus se termine avant de libérer une réservation, le prochain démarrage du planificateur efface le verrou obsolète.

Le comportement au démarrage est explicite. Lorsque le rattrapage est activé, les tâches en retard sont prises en compte pour exécution. Sinon, une tâche unique en retard est désactivée avec un résultat ignoré, tandis qu’une tâche récurrente avance à sa prochaine occurrence future sans enregistrer de résultat d’exécution. Le planificateur vérifie son jeton d’annulation entre les itérations de scrutation, de sorte que l’arrêt attend que le lot actuel de tâches dues se termine avant que la boucle ne se termine. L’annulation du planificateur ne garantit pas qu’un effet de bord externe déjà distribué puisse être annulé.

Exécutions SOP

Les définitions SOP se trouvent dans le répertoire sops configuré. SopEngine gère la progression de l’exécution, les attentes d’approbation, les points de contrôle, les transitions terminales et la surface d’état intégrée au processus. SopRunStore fait autorité en matière de concurrence lorsqu’il admet et réclame une exécution.

La persistance des exécutions est optionnelle. Avec la valeur par défaut sop.persist_runs = false, le moteur utilise un store en mémoire. Lorsque la persistance est activée, le backend SQLite par défaut écrit runs.db sous <data_dir>/sop, sauf si run_state_dir le remplace. Une initialisation réussie du store permet aux snapshots actifs, aux enregistrements terminaux, aux événements, aux révisions et aux revendications de concurrence de prendre en charge la restauration après redémarrage. Si l’initialisation du store échoue, le daemon consigne un avertissement et bascule vers le store en mémoire.

Les enregistrements d’audit SOP dans le backend Memory constituent une surface d’observabilité distincte. Ils ne remplacent pas le store d’exécution et ne doivent pas être utilisés comme référence faisant autorité pour déterminer si une exécution est active, en pause, approuvée ou terminale.

Les états d’approbation et de point de contrôle ne sont des états de contrôle persistants que lorsque le magasin des exécutions est persistant. La stratégie d’expiration reste en mode de refus par défaut : une approbation dont le délai a expiré est escaladée et continue d’attendre, sauf si la configuration sélectionne explicitement l’annulation ou le comportement historique d’approbation automatique.

Délégation et sous-agents

Les sous-agents héritent de la frontière de sécurité effective de leur parent. Les remplacements de stratégie et de mémoire peuvent restreindre l’enveloppe du parent mais ne peuvent pas l’élargir, et la comptabilisation des actions enfants utilise le suivi du parent, de sorte que la création d’enfants ne peut pas contourner le budget d’actions du parent.

Le chemin spawn_subagent est synchrone : le parent attend la fin de l’exécution de l’enfant, et ce chemin ne dispose d’aucun délai d’expiration local ni de gestionnaire d’annulation en arrière-plan.

L’outil delegate peut s’exécuter de manière synchrone ou démarrer une tâche en arrière-plan et renvoyer un UUID. Les résultats en arrière-plan sont écrits de manière atomique dans le workspace passé à l’outil et peuvent être vérifiés, listés, attendus par lot ou annulés. Un registre d’annulation en direct associe les identifiants de tâche à des jetons locaux au processus ; l’annulation met à jour le résultat persisté et signale la tâche en cours d’exécution lorsque ce jeton en direct est toujours disponible.

Sous un daemon démarré, les producteurs délégués et les sous-agents écrivent également des lignes de tâches dans le plan de contrôle durable. Ces écritures sont de type « best-effort » et indépendantes des écritures de fichiers de résultats délégués. Les lectures de résultats délégués restent prioritairement basées sur les fichiers ; seul un fichier encore marqué running est substitué par lost ou timed_out d’après l’état du plan de contrôle, de sorte que les deux enregistrements peuvent diverger.

Les lignes actuelles de délégué et de sous-agent renseignent l’agent, le statut, le PID propriétaire et l’ID de démarrage, la profondeur, et les horodatages. Elles laissent absents le heartbeat, la tâche parente, la route et le principal. La récupération au démarrage marque les lignes en cours d’exécution du démarrage précédent comme lost ; timed_out s’applique uniquement aux producteurs qui émettent des heartbeats obsolètes, ce que ces producteurs ne font pas actuellement. La ligne de tâche rend visible un enfant interrompu mais ne recrée pas son exécution.

Contrat cible du mode objectif

ADR-008 établit le plan de contrôle des tâches comme la future autorité pour le cycle de vie des objectifs, la propriété, la route, le principal, la relation parente et l’éligibilité à la récupération. Le dépôt contient le stockage des objectifs et les API du plan de contrôle, mais l’admission et l’exécution des objectifs en production ne sont pas encore intégrées de bout en bout.

Un chemin d’arrière-plan ne peut participer au mode objectif qu’après avoir préservé la relation d’objectif propriétaire et lui avoir signalé l’état terminal et l’utilisation du modèle. Jusqu’alors, ce chemin constitue un travail d’arrière-plan ordinaire plutôt qu’une exécution en mode objectif.

Liste de contrôle des modifications

Pour les modifications liées aux tâches en arrière-plan, répondez aux points suivants avant la validation par le relecteur :

• Quel sous-système gère le cycle de vie et quel magasin fait autorité ?
• Le traitement est-il local au processus, supervisé de manière durable ou réellement reprenable après redémarrage ?
• Quel jeton ou quelle action du plan de contrôle l’annule, et qu’est-ce qui peut rester en cours d’exécution ?
• Quels champs de tâche parente, d’agent, de route, de principal, de profondeur de récursion et d’utilisation ce chemin renseigne-t-il réellement ?
• Les états d’attente, d’approbation, de point de contrôle, perdus, expirés et terminaux sont-ils distinguables ?
• La récupération au démarrage peut-elle dupliquer un effet de bord ou laisser silencieusement une revendication en suspens ?
• La livraison du résultat reste-t-elle idempotente si l’achèvement est observé après un redémarrage ?

Pointeurs source

• Planificateur Cron et persistance : crates/zeroclaw-runtime/src/cron/scheduler.rs, crates/zeroclaw-runtime/src/cron/store.rs
• Moteur SOP et stockages des exécutions : crates/zeroclaw-runtime/src/sop/engine.rs, crates/zeroclaw-runtime/src/sop/store/
• Comportement de délégation et des sous-agents : Délégation et sous-agents, crates/zeroclaw-runtime/src/tools/delegate.rs, crates/zeroclaw-runtime/src/tools/spawn_subagent.rs, crates/zeroclaw-runtime/src/subagent/mod.rs
• Plan de contrôle des tâches durables et récupération : crates/zeroclaw-runtime/src/control_plane/
• Décision du mode objectif : ADR-008
• Guide de l’opérateur SOP : Fonctionnement des SOP