id: ADR-004 title: L’état partagé détenu par l’outil suit l’identité et la propriété des handles appartenant au démon date: 2026-03-22 status: accepté relates-to:

• https://github.com/zeroclaw-labs/zeroclaw/issues/4057
• crates/zeroclaw-runtime/src/tools/mod.rs
• crates/zeroclaw-tools/src/canvas.rs
• crates/zeroclaw-tools/src/reaction.rs
• crates/zeroclaw-api/src/tool.rs

ADR-004 : L’état partagé détenu par l’outil suit la propriété de l’identité et du handle détenue par le daemon

Il s’agit d’un enregistrement rétroactif restauré. L’ADR d’origine a été ajouté sous docs/architecture/adr-004-tool-shared-state-ownership.md et a été perdu lors de la migration mdBook. Les chemins de code ont été déplacés dans des crates du workspace depuis l’enregistrement d’origine ; cette version restaurée conserve la décision acceptée intacte tout en mettant à jour les références de chemins là où cela est utile.

Contexte

Les outils ZeroClaw s’exécutent dans un environnement multi-clients où un seul processus démon peut servir plusieurs clients connectés et sessions d’agents. Certains outils nécessitent un état partagé de longue durée :

• les outils délégués conservent des handles vers les outils parents ;
• les outils orientés canaux conservent des handles vers les maps de canaux ;
• l’outillage canvas maintient l’état d’affichage partagé ;
• les outils futurs peuvent conserver des limiteurs de débit, des pools de connexions, des handles d’identifiants ou des caches à portée de session.

Ces états ne peuvent pas tous être traités de la même manière. Certains sont des états d’affichage ou de registre partagés légitimes. Certains sont sensibles à la sécurité et doivent être isolés par client ou par session.

Sans un contrat partagé, les nouveaux outils risquent d’introduire un état dupliqué, des fuites de données entre clients, un état obsolète après rechargements, ou de bloquer la validation de démarrage dans la mauvaise phase du cycle de vie.

Décision

Les outils peuvent posséder un état partagé de longue durée lorsqu’ils suivent le modèle de handle et respectent l’identité, l’isolation, le cycle de vie et les règles de rechargement appartenant au démon.

1. Propriété

Lorsqu’un outil possède légitimement un état partagé, il utilise un handle clonable passé au moment de la construction, généralement un Arc<RwLock<T>> ou un wrapper étroit autour de celui-ci.

Les exemples dans l’espace de travail actuel incluent :

Les outils qui nécessitent un état partagé doivent :

• définir un type de handle nommé ou un wrapper ;
• accepter le handle au moment de la construction ;
• documenter le contrat de concurrence et de possession ;
• éviter l’état global mutable pour les données par requête ou par client.

2. Identité

Le démon possède l’identité du client et de la session. Les outils ne doivent pas construire leurs propres clés d’identité client durables à partir des détails de transport tels que les adresses IP, les en-têtes, les noms d’utilisateur ou les chaînes d’expéditeur spécifiques au canal.

Les outils qui ont besoin d’un espace de noms par client consomment l’identité assignée par le démon ou reçoivent un handle déjà scopé. Les outils qui n’ont pas besoin d’isolation par client peuvent ignorer la surface d’identité, mais ils ne doivent pas en inventer une parallèle.

3. Cycle de vie

Le cycle de vie d’un outil comporte quatre phases :

1. Construction : instancier avec des handles et des entrées dérivées de la configuration. Ne pas effectuer de validation réseau ou sur le système de fichiers bloquante.
2. Enregistrement : s’enregistrer dans le registre d’outils. Un outil peut effectuer une validation au démarrage si cette validation est requise avant utilisation.
3. Exécution : traiter une seule requête. Évitez de bloquer la validation ou les reconstructions du registre dans ce chemin d’exécution.
4. Arrêt : nettoyer les ressources possédées via Drop ou une méthode d’arrêt explicite lorsque le propriétaire en fournit une.

L’état de validation dérivé de la configuration, des identifiants, de la politique ou de ressources externes doit être invalidé lorsque la source change. L’état d’affichage non lié à la sécurité peut survivre aux rechargements uniquement lorsque le rechargement n’affecte pas sa validité.

4. Isolation

L’état susceptible de fuiter des identifiants, une politique, des quotas, des données utilisateur ou des données de session doit être isolé par client, agent ou session selon la surface propriétaire. Un handle partagé ne doit pas stocker de secrets par client sauf si l’espace de clés est délimité par une identité détenue par le démon.

L’état naturellement partagé, tel que l’état d’affichage de diffusion, les données de registre en lecture seule ou les handles de canal, peut être partagé entre clients. Lorsqu’il utilise des clés de type chaîne, il doit prendre en charge le préfixage de namespace ou les métadonnées de trace afin que les opérateurs puissent toujours filtrer par client, agent, canal ou session.

5. Recharger les sémantiques

Les validations et les caches dérivés de la configuration deviennent invalides après la modification de la configuration, des identifiants, des politiques, de l’espace de travail ou de la source du fournisseur correspondante. L’outil doit soit résoudre à nouveau à partir de la source de vérité au moment de l’utilisation, soit recevoir une nouvelle valeur handle ou dérivée de la configuration du propriétaire.

La règle de rechargement concerne la validité, pas la mutation du registre. Un outil peut conserver un état d’affichage non lié à la sécurité à travers les rechargements uniquement lorsque le rechargement n’affecte pas la validité de cet état.

Conséquences

Conséquences positives :

• L’état appartenant à l’outil devient découvrable et auditable.
• Les données sensibles à la sécurité ont une exigence d’isolation nommée.
• Le comportement de rechargement à l’exécution a une règle d’invalidation claire.
• Les nouveaux outils peuvent réutiliser le modèle de handle sans inventer d’état global.
• Les réviseurs peuvent demander la source de vérité avant d’accepter un nouveau champ d’outil ou un cache.

Conséquences négatives :

• Les outils qui ressemblent à de simples singletons doivent tout de même raisonner sur l’identité du client, de l’agent et de la session.
• Certains handles plus anciens nécessitent une migration lorsque la surface d’identité du daemon ou le modèle de rechargement change.
• Le modèle de handle ne suffit pas à lui seul ; la propriété et l’état canonique doivent encore être nommés lors de la revue.

Références

• Inventaire des outils intégrés
• Problème #4057
• AGENTS.md
• crates/zeroclaw-runtime/src/tools/mod.rs
• crates/zeroclaw-tools/src/ask_user.rs
• crates/zeroclaw-tools/src/poll.rs
• crates/zeroclaw-tools/src/reaction.rs
• crates/zeroclaw-tools/src/canvas.rs
• crates/zeroclaw-api/src/tool.rs
• crates/zeroclaw-gateway/src/lib.rs