Mécanismes internes du runtime

Cette page est le complément d’architecture de la section Agents : elle décrit comment le runtime applique les autorisations par agent, cloisonne la mémoire et attribue les journaux. Pour configurer et exécuter des agents, commencez par Agents ; pour la référence des champs du schéma, consultez Configuration ; pour les étapes de mise en place en conditions réelles, consultez Configuration multi-agent.

Modèle d’autorisations

Le SecurityPolicy effectif de chaque agent est construit par SecurityPolicy::for_agent(config, alias) :

Partez du profil de risque de l’agent ([risk_profiles.<profile>]).
Définit la limite sur le répertoire de l’espace de travail propre à chaque agent (<install>/agents/<alias>/workspace/).
Parcourir [agents.<alias>.workspace.access] :
- Read → l’espace de travail du frère ou de la sœur arrive dans la liste d’autorisations en lecture seule.
- Write → l’espace de travail voisin est ajouté à la liste d’autorisation en écriture seule
- ReadWrite → le workspace du frère est ajouté à la liste d’autorisation en lecture-écriture.
Si [agents.<alias>.workspace.unrestricted_filesystem] vaut true, désactivez workspace_only.

La liste d’autorisation en lecture seule est respectée par file_read et les autres outils de lecture, y compris les commandes git_operations status, diff, log, branch, stash-list et worktree-list. La commande worktree list ne renvoie que les entrées dont le chemin de l’arbre de travail se résout et dont les métadonnées Git peuvent être validées via l’autorisation de lecture applicable. La liste d’autorisation en lecture-écriture régit file_write, file_edit, les commandes git_operations classées en écriture (y compris worktree add/remove/prune), ainsi que les invocations de l’outil shell qui touchent des chemins. Un espace de travail voisin en écriture seule n’est pas disponible pour git_operations : Git doit lire les métadonnées du dépôt avant toute opération. Les cibles des arbres de travail et les métadonnées .git/gitdir/commondir des arbres de travail liés doivent se trouver dans l’autorisation applicable. git_operations rejette les liens symboliques présents à n’importe quel endroit de ces métadonnées au lieu de les suivre, même lorsque leur cible finale serait autorisée. Les invocations Git suppriment les variables GIT_* héritées ; configurez l’identité de commit dans la configuration Git du dépôt ou la configuration globale plutôt que dans des variables d’environnement. Les commandes en lecture seule suppriment les intégrations exécutables configurées dans le dépôt ainsi que la résolution d’identité via mailmap ; leur format de log fixe utilise aussi les champs auteur bruts, donc ces commandes ne lisent jamais .mailmap ni mailmap.file. Elles interdisent le transport Git et désactivent la récupération implicite d’objets promisor, de sorte qu’une lecture nécessitant un objet indisponible d’un clone partiel échoue au lieu de lancer un transport choisi par le dépôt. Les commandes d’écriture conservent les hooks Git ordinaires et les filtres lorsque l’opérateur accorde l’accès en lecture-écriture, et appliquent la frontière de bac à sable configurée par agent. Avec [runtime] kind = "docker", les commandes git_operations classées en écriture sont rejetées avant le lancement de toute commande Git d’écriture, car Git n’entre pas dans le conteneur d’exécution ; les commandes classées en lecture sont inchangées, et l’outil shell reste le chemin de commande dans le conteneur. En mode d’exécution natif, un bac à sable sans effet ne confine donc pas Git. Seul le backend Landlock étend ce bac à sable aux racines voisines configurées ; les autres backends peuvent rejeter les écritures en dehors de l’espace de travail de l’agent, monter l’espace de travail en lecture seule, omettre l’espace de travail ou masquer la configuration Git globale. Voir Bac à sable pour le comportement de chaque backend. Les fichiers de périphériques POSIX (/dev/null, /dev/zero, /dev/random, /dev/urandom) sont toujours lisibles afin que les idiomes shell continuent de fonctionner sans configuration par agent.

Les instances SubAgent créées appliquent la règle selon laquelle un enfant ne peut pas obtenir de privilèges supérieurs à ceux de son parent. La liste complète des axes du validateur et le comportement de partage du budget sont documentés dans Delegation → Permission inheritance.

Tours à outil unique

Les tours à un seul outil demandent au plus un appel d’outil natif par réponse du fournisseur. La boucle d’agent existante exécute cet appel, enregistre son résultat et demande au fournisseur la réponse suivante dans le même tour d’utilisateur. Le modèle peut commenter entre les appels, mais ce commentaire n’est ni requis ni généré par ZeroClaw.

Ce mode est désactivé par défaut. Dans ZeroCode Config, définissez runtime_profiles.<profile>.single_tool_rounds sur true et sélectionnez ce profil avec agents.<alias>.runtime_profile. Une valeur non définie ou false conserve le comportement par lots. Ce réglage est indépendant de parallel_tools, qui contrôle la concurrence d’exécution d’un lot admis, et non le nombre d’appels que le fournisseur peut renvoyer.

Seules les routes de fournisseur prises en charge activent la politique. Si la route sélectionnée ou une route de repli accessible ne prend pas en charge cette fonctionnalité, ZeroClaw conserve le comportement par lots et affiche un avis de limitation une seule fois par tour. Lorsqu’une politique est active, une réponse contenant plusieurs appels d’outils, natifs ou récupérés, échoue avant que l’un de ces appels ne soit exécuté ou n’entre dans l’historique des échanges d’outils. L’utilisation de la requête fournisseur rejetée est tout de même comptabilisée dans les jetons et les coûts. Le texte narratif diffusé en continu peut déjà être visible ; ZeroClaw ne rejoue pas une réponse non conforme.

L’approbation des outils, les reçus, l’annulation et les limites d’itérations conservent leur comportement existant. Les appels séquentiels peuvent nécessiter davantage de requêtes au fournisseur, augmenter la latence et atteindre max_tool_iterations plus tôt. Pour revenir en arrière, définissez single_tool_rounds à false ou supprimez-le du profil d’exécution sélectionné.

Modèle de mémoire

Chaque agent possède sa propre instance Arc<dyn Memory>. La fabrique (zeroclaw_memory::create_memory_for_agent) répartit selon le type de backend :

SQLite / Postgres / Lucid : magasin partagé à l’échelle de l’installation. La table agents associe alias → UUID, et la table memories porte agent_id, qui référence cet UUID. La fabrique encapsule le backend interne dans AgentScopedMemory, qui appose l’UUID de l’agent lié à chaque écriture via store_with_agent et filtre chaque rappel via recall_for_agents avec la liste d’autorisation résolue. Les autorisations structurées peuvent restreindre davantage chaque agent voisin à des noms de catégorie exacts ; l’agent lié voit toujours toutes ses propres catégories.
Répertoire par agent. Chaque agent écrit avec MarkdownMemory dans <install>/agents/<alias>/workspace/MEMORY.md et memory/YYYY-MM-DD.md. Comme Markdown ne conserve pas les catégories personnalisées par ligne, le validateur de configuration et la fabrique rejettent les autorisations limitées à une catégorie pour ce backend ; seules les autorisations sans restriction vers les agents pairs sont acceptées. Le wrapper filtre tout de même par précaution toute construction directe de pair.
Qdrant : collection partagée, indexée par payload. Le champ de payload agent_id assure l’attribution par agent ; recall_for_agents sur-récupère puis post-filtre selon le payload.
None : stub no-op. Le wrapper existe toujours afin que le chemin d’exécution soit uniforme.

La mémoire inter-backend et inter-agents n’est pas prise en charge : le validateur de schéma, au chargement de la configuration, rejette les entrées read_memory_from qui pointent vers un agent frère sur un backend différent. Les autorisations par catégorie sont à correspondance exacte et non transitives ; une catégorie inconnue ne correspond à aucune ligne.

Cycle de vie du renommage et de la suppression

Utilisez les contrôles d’agent du tableau de bord de la passerelle ou la CLI dédiée zeroclaw agents pour renommer et supprimer. Dans la version standard avec gateway et agent-runtime activés, les deux interfaces exécutent les cascades de références et d’état possédé ; le fait de supprimer ou de re-clé directement agents.<alias> en TOML ou via un setter de configuration générique ne le fait pas. Une CLI à fonctionnalités réduites met toujours à jour les références de configuration mais avertit que l’état possédé n’a pas été cascadé ; utilisez donc une version avec les deux fonctionnalités activées pour les opérations de cycle de vie.

Les deux opérations rendent la modification de configuration durable avant d’exécuter les effets de bord sur l’état détenu. Le renommage réécrit d’abord les références de configuration, puis déplace l’espace de travail par défaut associé à l’alias et repointe l’état de la mémoire, du cron, d’ACP et des sessions. La suppression refuse d’abord les références strictes et les sessions ACP actives, puis retire l’entrée de configuration et les références souples avant de tenter l’archivage de l’espace de travail, l’export et le nettoyage de l’état détenu, ainsi que l’effacement de l’attribution des sessions.

Les effets de bord post-persistance sont faits au mieux et signalent les échecs détectés, mais les échecs d’écriture de fichiers d’archive peuvent n’apparaître que dans les journaux de la passerelle. Les avertissements de renommage invitent à réessayer le même renommage via l’API de la passerelle pour converger les résidus laissés sous l’ancien alias. Après suppression, vérifiez le contenu de l’archive et les journaux avant de vous appuyer sur l’archive pour la récupération. La restauration automatisée n’est pas prise en charge.

Voir Guide de configuration multi-agents pour les contrôles actuels, les blocages, la structure des archives et les vérifications opérateur.

Non pris en charge actuellement

Accès mémoire inter-agents entre back-ends (par exemple, un agent SQLite lisant les lignes d’un agent Postgres).
Restauration automatisée à partir d’une archive de suppression d’agent.
Espacement de noms des secrets par agent : il existe un seul SecretStore à l’échelle de l’espace de travail.
Extensions du format de communication Lucid pour la définition de portée inter-agents.