Fonctionnement des SOP

Contrat d’exécution

• Les définitions des SOP sont chargées depuis <shared>/sops/<sop_name>/SOP.toml, avec un fichier SOP.md facultatif.
• CLI zeroclaw sop gère les définitions hors ligne : list, validate, show, graph, rename, delete.
• Les exécutions SOP sont lancées par un fan-in d’événements en direct (webhook authentifié, MQTT, système de fichiers ou AMQP), par le tick périodique de maintenance SOP du daemon pour les déclencheurs cron, ou par l’outil intégré à l’agent sop_execute. Les autres types de déclencheurs (périphérique et calendrier) sont définis et mis en correspondance, mais ne sont pas encore reliés à une source d’événements en direct (voir SOP Fan-In).
• La progression des tâches utilise les outils : sop_status, sop_approve, sop_advance.
• Par défaut, l’état d’exécution est local au processus. Avec sop.persist_runs = true, une initialisation réussie du backend SQLite par défaut le stocke sous <data_dir>/sop/runs.db et restaure les exécutions actives après un redémarrage. En cas d’échec de l’initialisation, un avertissement est consigné et le système bascule sur la mémoire locale au processus.
• Les journaux d’audit des SOP sont persistés dans le backend Memory configuré sous la catégorie sop.

L’état d’exécution et l’historique d’audit sont des surfaces distinctes. Consultez Cycle de vie des travaux en arrière-plan pour la gestion du cycle de vie, l’annulation et la sémantique du redémarrage.

Flux d’événements

graph LR
    MQTT[MQTT listener] -->|topic match| Dispatch
    TOOL[sop_execute tool] -->|manual| Dispatch
    WH[Webhook request] -->|authenticated HTTP fan-in| Dispatch
    CRON[Cron trigger] -->|daemon maintenance tick| Dispatch
    GPIO[Peripheral trigger] -.->|defined, unwired| Dispatch

    Dispatch --> Engine[SOP Engine]
    Engine --> Run[SOP Run]
    Run --> Action{Action}
    Action -->|ExecuteStep| Agent[Agent Loop]
    Action -->|WaitApproval| Human[Operator]
    Human -->|sop_approve| Run

Prise en main

1. Par défaut, sops_dir n’est pas défini ; le chargement des SOP à l’exécution est donc désactivé. Activez-le en définissant sops_dir via la passerelle, zerocode ou zeroclaw config set. Une valeur relative est résolue par rapport à la racine de l’installation (le répertoire contenant config.toml) ; ainsi, la valeur documentée shared/sops donne <install>/shared/sops, le même répertoire que celui dans lequel l’auteur de la SOP écrit. Une valeur absolue ou préfixée par ~- est utilisée telle quelle. Redéfinir sops_dir sur "" (ou le supprimer) désactive à nouveau le chargement des SOP à l’exécution ; la CLI utilise néanmoins <install>/shared/sops comme solution de repli pour l’inspection hors ligne.

   Vous migrez depuis une version antérieure ? Les valeurs relatives de sops_dir sont désormais résolues par rapport à la racine d’installation, comme les répertoires skill-bundles. Les versions antérieures utilisaient deux racines différentes pour le même paramètre ; vérifiez-les toutes les deux avant la mise à niveau :

   Faire apparaître dans les versions antérieures	Racine utilisée	Où sops_dir = "shared/sops" a atterri
   Chargement à l’exécution et CLI locale zeroclaw sop	data_dir	<data_dir>/shared/sops
   Rédaction de SOP Web et RPC	<install>/shared	<install>/shared/shared/sops (segment dupliqué)

   Les deux pointent désormais vers l’unique emplacement canonique <install>/shared/sops. Inspectez les deux anciens emplacements et déplacez toutes les définitions que vous y trouvez vers <install>/shared/sops ; les définitions laissées dans l’une ou l’autre arborescence deviennent invisibles après la mise à niveau. Les définitions créées via l’ancienne interface web ou RPC sont les plus faciles à manquer, car elles se trouvent dans le chemin d’écriture doublé plutôt qu’à l’emplacement décrit dans la documentation.

   Toute autre valeur relative est déplacée de la même manière : sops_dir = "my-sops" passe de <data_dir>/my-sops (à l’exécution et via la CLI) ou de <install>/shared/my-sops (pour la création via le web et RPC) à <install>/my-sops. Les valeurs absolues et celles préfixées par ~-restent inchangées.

   Le cas non défini évolue lui aussi : la solution de repli de la CLI hors ligne analysait auparavant <data_dir>/sops et analyse désormais <install>/shared/sops.

   zeroclaw sop list lit le nouvel emplacement, donc une liste vide après la mise à niveau signifie que les définitions se trouvent encore dans l’une des anciennes arborescences.

2. Créez un répertoire de procédures opérationnelles standard (SOP), par exemple :

   ~/.zeroclaw/shared/sops/deploy-prod/SOP.toml
   ~/.zeroclaw/shared/sops/deploy-prod/SOP.md
   

3. Valider et inspecter les définitions :

   sh

   zeroclaw sop list
   zeroclaw sop validate
   zeroclaw sop show deploy-prod
   

4. Le déclencheur s’exécute via des sources d’événements configurées, ou manuellement depuis un tour d’agent avec sop_execute.

Renommer un SOP

Le nom d’une SOP est son adresse : la définition se trouve dans <sops>/<name>/, et chaque interface d’édition enregistre une SOP sous le nom qui lui a été transmis. Enregistrer une SOP modifiée sous un autre nom écrirait une seconde copie et laisserait l’original en place. C’est pourquoi l’enregistrement d’une modification rejette tout changement de nom. Le renommage est une opération distincte.

zeroclaw sop rename deploy-prod deploy-production

Le daemon expose la même opération sous forme de méthode RPC sops/rename, qui prend {"from": "...", "to": "..."}, et sous forme de POST /api/sops/{name}/rename avec un corps {"to": "..."}. Un nom cible déjà utilisé renvoie un conflit (409, code RPC -32020) ; un SOP source inconnu renvoie une erreur « non trouvé » (404, code RPC -32021).

Un renommage :

• refuse un nom cible déjà utilisé, si bien qu’il ne peut jamais fusionner deux SOP ;
• refuse une cible qui n’est pas un composant de chemin unique, la même vérification qu’appliquent toutes les autres opérations SOP prenant un nom ;
• refuse une source qui n’est pas un répertoire réel situé dans la racine SOP. Un lien symbolique à cet emplacement passerait la vérification de nom, puis redirigerait chaque lecture et écriture vers sa cible. Il faut donc vérifier le nom sans suivre les liens et confirmer que la source se résout à l’intérieur de la racine avant de lire quoi que ce soit ;
• relance la validation stricte à l’enregistrement, si bien qu’elle ne peut pas réécrire sur le disque une définition que l’interface de création aurait refusé d’écrire;
• modifie uniquement la valeur de namedans la section[sop]deSOP.toml, en conservant le commentaire et l'espacement de cette ligne. Les étapes, les déclencheurs, les autres commentaires et SOP.md restent exactement tels quels ; seul changement cosmétique : un nom entre guillemets simples est restitué entre guillemets doubles.

Le déplacement du répertoire est un unique renommage du système de fichiers, et il intervient en dernier. La SOP n’existe donc qu’à un seul endroit à chaque instant : un renommage interrompu ne peut laisser ni deux copies, ni aucune. Si un renommage est interrompu entre la réécriture du manifeste et le déplacement, la SOP conserve son ancien répertoire alors que le manifeste porte déjà le nouveau nom, de sorte que zeroclaw sop list affiche le nouveau nom. Relancer le même renommage termine l’opération.

Le renommage réécrit la définition sur le disque, exactement comme l’enregistrement ou la suppression d’une définition. Un démon qui a déjà chargé l’ancienne définition continue de l’exécuter jusqu’à ce qu’il recharge ses SOP ; l’historique d’exécution, les enregistrements d’audit et tout autre élément ayant capturé l’ancien nom conservent l’ancien nom.

Les écritures liées à l’authoring sont sérialisées. La création, l’enregistrement, la suppression et le renommage acquièrent tous un verrou consultatif sur le fichier .sop-authoring.lock situé à la racine du SOP avant de toucher à quoi que ce soit, de sorte que deux de ces opérations ne peuvent pas s’entrelacer, même entre processus : la CLI qui écrit dans une racine où un démon en cours d’exécution écrit également attend son tour au lieu de la concurrencer. Un appel d’authoring qui ne peut pas acquérir le verrou dans les dix secondes échoue au lieu d’attendre indéfiniment. Les lectures ne sont pas sérialisées. Chaque fichier écrit par un appel d’authoring est remplacé par un renommage atomique, de sorte qu’un lecteur ne voit jamais un fichier tronqué ou partiellement écrit. Un enregistrement écrit deux fichiers, SOP.toml et SOP.md, l’un après l’autre ; un lecteur qui s’exécute pendant un enregistrement peut donc voir brièvement le manifeste d’une révision et les étapes d’une autre, et un lecteur qui entre en concurrence avec le premier enregistrement d’un nouveau SOP peut voir son manifeste avant que ses étapes n’existent. La lecture suivant l’enregistrement voit les deux fichiers à la nouvelle révision.

Chaque étape est validée par un renommage, de sorte qu’un lecteur ordinaire comme un processus interrompu ne voit jamais une étape à moitié terminée. Le répertoire contenant chaque entrée renommée est ensuite vidé sur le disque (flush), de sorte que sous Unix l’ordre survit également à un plantage de la machine. Si ce flush échoue après que le renommage a déjà eu lieu, l’opération se termine tout de même et l’échec est journalisé : le changement est complet et visible, et seule la garantie de survie à un plantage pour cette entrée est perdue. macOS respecte le flush pour l’ordre sans forcer le vidage du cache du périphérique, et Windows ne dispose d’aucune primitive de synchronisation de répertoire ; sur ces plateformes, la dernière étape de la garantie relève donc du système de fichiers et non de ce que ZeroClaw peut imposer.

Pour les détails sur le routage des déclencheurs et l’authentification, consultez SOP Fan-In.