Schedule dans Kavor : donnez une horloge à votre graphe

Schedule est une cause visible d’activité : vous choisissez quand une action doit survenir, connectez une cible unique et conservez chaque tentative inspectable dans le Canvas.

Dans le domaine Kavor, Schedule est la source de Trigger disponible. Il n’effectue pas le travail et ne décide pas s’il faut agir. Il a deux responsabilités : quand déclencher et quel payload livrer.

La cible donne son sens au payload :

• avec un CodingAgent, le payload est un prompt ;
• avec un Terminal, le payload est une commande shell.

Le reste appartient à la cible. Workspace, répertoire, provider ou shell, Git mode, permissions, Guardrails et contexte du graphe restent inchangés.

Voir l’image en taille réelle

Schedule lance l’activité ; le CodingAgent utilise le contexte accessible pour exécuter et expliquer le résultat.

Trois usages qui justifient un Schedule

Réveiller un Maintainer avec le contexte

Un Schedule livre chaque jour un prompt à un CodingAgent. Celui-ci atteint une Specification contenant le contrat de maintenance, un Terminal pour les contrôles, un File d’entrée, une Sticky Note pour le rapport et un Reviewer pour une évaluation indépendante.

Schedule crée la cause ; le graphe apporte intention, outils, mémoire et collaboration.

Exécuter une commande opérationnelle visible

Un Schedule directement connecté à un Terminal peut livrer un contrôle, un script ou une commande de maintenance. Si un File est aussi connecté au Terminal par une variable d’environnement, la commande utilise son chemin canonique sans copier de valeurs entre fenêtres.

sqlite3 app.db < "$CHECK_SQL"

Le processus reste dans le vrai Terminal. L’historique enregistre ce que Kavor a pu observer sur la livraison sans inventer une réussite à partir du texte du shell.

Créer un petit système semi-autonome

Schedule — Maintainer — Specification
                      ├─ Terminal
                      ├─ File
                      ├─ Sticky Note
                      └─ Reviewer

Les lignes sont des Connections sans direction persistée. Schedule a une cible directe : Maintainer. Le CodingAgent utilise le reste du composant accessible et laisse des preuves pour la décision humaine.

Configurez d’abord, libérez l’horloge ensuite

Un nouveau Schedule commence Paused comme exécution unique future. Vous pouvez ainsi écrire le payload, choisir la récurrence, connecter la cible et vérifier l’aperçu avant d’autoriser l’activité.

Ordre recommandé :

1. ajoutez un Schedule au Canvas ;
2. écrivez un payload spécifique et vérifiable ;
3. choisissez une exécution unique ou récurrente ;
4. contrôlez Next occurrences et le fuseau affiché ;
5. connectez directement un CodingAgent ou Terminal ;
6. utilisez Resume seulement lorsque la structure est prête.

Un Trigger peut rester sans cible pendant sa configuration. Un Schedule actif sans Connection de cible enregistre l’occurrence comme Blocked ; Run now sans cible est refusé avant la création d’une tentative.

Écrivez un payload qui peut se terminer

Un bon prompt précise l’objectif, les ressources du graphe, les preuves attendues et la condition d’arrêt :

Analyse les échecs CI récents. Exécute seulement les contrôles pertinents dans le Terminal Checks, consigne un résumé étayé dans la Sticky Note Daily report et demande au Reviewer une évaluation indépendante. Ne modifie pas le code avant d’avoir consigné la cause probable et arrête-toi si la correction exige d’élargir la Specification.

Une bonne commande Terminal est explicite, non interactive et produit un résultat observable :

pnpm test -- --runInBand

Le payload ne remplace pas les Connections. Citer une Sticky Note, un File ou une Specification ne donne pas accès si le Node n’appartient pas au composant accessible du CodingAgent.

Exemple complet : une vérification quotidienne avec rapport

Vous voulez détecter les pannes tôt et trouver un résumé utile en ouvrant le projet. Reliez un Schedule au Maintainer. Dans son graphe, gardez une Specification définissant la routine, Terminal Checks et Sticky Note Daily report. Ajoutez un Reviewer si la routine a réellement besoin d'une autre évaluation.

Dans la Specification, définissez les vérifications et la réponse à leurs échecs. Commencez par le diagnostic et le rapport ; autorisez séparément les corrections quand la cause et le périmètre sont clairs.

Un payload possible :

Exécute les vérifications autorisées par la Specification dans Terminal Checks. Lis les scripts du projet pour choisir les bonnes commandes. Note l'heure, les commandes, résultats et points en attente dans Sticky Note Daily report. Ne modifie pas le code et ne publie rien. Si une vérification ne peut pas tourner, note pourquoi. Termine par une prochaine action concrète, puis arrête-toi.

Configurez Daily, choisissez une heure où la machine sera éveillée et vérifiez Next occurrences. Avant Resume, utilisez Run now avec le Schedule en pause et vérifiez :

1. le prompt est arrivé au bon Maintainer ;
2. les vérifications ont tourné dans le Terminal prévu ;
3. la note distingue réussite, échec et non-exécution ;
4. l'historique montre le résultat observé de la tentative.

Exemple de rapport :

## Vérification quotidienne
- Tests : réussis ; commande et résumé consignés dans Terminal Checks.
- Build : échoué ; erreur d'import identifiée dans le fichier référencé.
- Prochaine action : revoir l'import avant d'autoriser une correction.
- Modifications du code : aucune.

Après le test, utilisez Resume. Si la machine est éteinte à l'occurrence suivante, consultez Missed et décidez quand lancer manuellement ; n'attendez pas d'exécution rétroactive. Si la routine dure plus que l'intervalle, revoyez la récurrence plutôt que d'attendre une file illimitée.

La récurrence sans masquer le calendrier

L’éditeur propose Once, Hourly, Daily, Weekdays, Weekly, Monthly et Custom pour une expression cron avancée. Les presets et l’éditeur avancé modifient la même expression : il n’existe pas deux plannings parallèles. L’intervalle minimal est d’une minute. N’approximez pas avec cron une récurrence qu’il ne représente pas correctement, comme « toutes les deux semaines à partir de cette date ».

Kavor enregistre un fuseau IANA explicite et affiche les prochaines occurrences dans le fuseau local de la machine qui présente le Canvas. Le fuseau n’est pas modifiable dans l’interface ; il provient de l’hôte lors de l’enregistrement. Vérifiez l’aperçu avant Resume.

Lors du passage à l’heure d’été ou d’hiver, une heure locale répétée ne déclenche qu’une fois. Une heure inexistante est déplacée vers le premier instant local valide. Dans le preset mensuel, un jour absent du mois est ignoré : le 31 ne s’exécute pas en février.

Pause, Resume et Run now sont différents

• Pause arrête immédiatement les nouvelles occurrences. La période en pause ne crée ni tentative ni Missed.
• Resume ne considère que les occurrences futures et exige un payload valide ; une exécution unique doit encore être dans le futur.
• Run now crée une tentative manuelle indépendante, fonctionne en pause et ne déplace pas la récurrence suivante.

Run now sert à valider le payload et la cible avant de libérer l’horloge. Ce n’est pas un retry automatique et il ne change pas l’état Paused ou Running. Une exécution Once revient à Paused après son instant ; l’historique et Run now restent disponibles.

Quand l’heure arrive

Kavor stocke une tentative durable et arbitre la livraison avec les messages déjà acceptés par la cible. La tentative peut passer par Pending et Delivering avant le résultat observé.

• Completed — Kavor a observé la fin ;
• Needs attention — le CodingAgent demande une intervention et peut encore terminer ;
• Fired — la livraison a eu lieu mais ce chemin n’expose pas de fin observable ;
• Failed — un échec observable s’est produit ;
• Interrupted — la livraison a commencé sans résultat fiable ;
• Blocked — la cible ou le Workspace était indisponible ;
• Missed — l’instant est passé sans que le runtime puisse le réclamer ;
• Coalesced — une autre tentative occupait déjà l’unique emplacement en attente de la cible.

L’heure planifiée ne prouve pas l’exécution. Consultez le dernier état du Node et l’historique pour l’heure nominale, la livraison, le résultat et le diagnostic.

Quand la machine dort ou que Kavor est fermé

Schedule dépend du runtime local : Kavor doit fonctionner, la machine être éveillée, l’utilisateur authentifié et la session de la cible ouverte.

Au démarrage de l'application, Kavor restaure les sessions marquées pour rester ouvertes lorsqu'elles sont ciblées par des Triggers actifs. Cela inclut les autres Workspaces de l'utilisateur, pas seulement celui qui est visible. Les Triggers en pause ne restaurent rien et une session volontairement fermée reste fermée.

Si plusieurs occurrences passent pendant l’indisponibilité, Kavor ne conserve que la plus récente occurrence manquée de ce Schedule. Il n’exécute pas d’ancien travail par surprise au retour. L’interface affiche Missed et propose une action explicite équivalente à Run now.

Il n’y a ni catch-up automatique ni retry des effets externes.

La restauration des sessions s'applique aussi au démarrage normal de l'application, pas uniquement au démarrage en arrière-plan.

Quand la cible est déjà occupée

Schedule conserve au maximum une tentative en attente pendant que la cible travaille. Les nouvelles occurrences arrivant lorsque cet emplacement est occupé sont Coalesced et ne seront pas livrées plus tard.

Si la tâche peut durer plus longtemps que la récurrence, augmentez l’intervalle ou rendez la réconciliation de l’état courant idempotente dans la cible.

Limites à prendre en compte

• un Schedule a au maximum une cible directe, CodingAgent ou Terminal ;
• il ne démarre pas une session que vous avez volontairement fermée ;
• seules les cibles marquées pour rester ouvertes sont restaurées au démarrage, et seulement pour les Triggers actifs ;
• il n’étend ni le graphe, ni les permissions, ni les Guardrails de la cible ;
• il ne remplace pas les critères d’acceptation et ne juge pas la correction du résultat ;
• il effectue au maximum une tentative automatique de livraison par tentative enregistrée ;
• il ne promet pas d’effet externe exactement une fois ;
• il n’accumule pas toutes les occurrences Missed ou Coalesced pour plus tard.

Si le travail exige fan-out, approbation par étapes, compensation ou orchestration transactionnelle, modélisez ces responsabilités dans le graphe et gardez la décision humaine explicite.

Checklist avant Resume

• le payload précise-t-il objectif, preuve et condition d’arrêt ?
• Next occurrences correspond-il à l’heure attendue ?
• le fuseau affiché est-il correct ?
• existe-t-il exactement une Connection de cible ?
• la session de la cible est-elle marquée pour rester ouverte ?
• le graphe ne contient-il que le contexte et les capacités nécessaires ?
• répéter est-il sûr si un effet externe a déjà eu lieu ?
• savez-vous où consulter résultat et historique ?

Continuer

• Consultez la matrice des Connections.
• Comprenez comment les CodingAgents voient et construisent le Canvas.
• Utilisez CodingAgents et rôles pour séparer maintenance, revue et décision.