Piloter Studio avec un agent de navigateur

Verbatra Studio est d'ordinaire une surface humaine : tu ouvres le tableau de bord en loopback et tu parcours au clic l'état du projet, la dérive, la file de révision et les modifications. Avec l'option facultative --expose-agent-tools, Studio enregistre en plus ces mêmes actions de révision comme outils WebMCP, si bien qu'un agent IA de navigateur (par exemple Gemini ou Claude tournant dans Chrome), posé sur ce même onglet ouvert et authentifié, peut les piloter de façon structurée au lieu de deviner à partir du DOM.

C'est fait pour piloter un projet verbatra existant par la conversation : inspecter l'état et la dérive, traiter la file de révision, modifier des entrées, et (seulement si tu autorises aussi la dépense) retraduire et traduire les clés en attente. Ce n'est pas fait pour la mise en place d'un projet, ni pour un accès distant.

Ce qu'est WebMCP

WebMCP permet à une page d'enregistrer sur document.modelContext des outils qu'un agent IA résidant dans le navigateur peut ensuite appeler. Studio s'en sert pour annoncer ses actions de révision comme des outils nommés. Chaque appel d'outil passe toujours par exactement le même RPC authentifié que le tableau de bord, sur la même origine loopback, avec la même validation d'entrée et les mêmes contrôles de capacité. Enregistrer les outils n'accorde à un agent rien que l'onglet ouvert et authentifié ne possédait déjà : un agent pilotant le DOM pouvait déjà atteindre chacune de ces actions. La surface se confond avec cet unique onglet ouvert et n'ajoute aucune exposition réseau nouvelle.

Prérequis du navigateur

• Un navigateur compatible WebMCP. Aujourd'hui cela veut dire Chrome 149 ou plus récent avec chrome://flags/#enable-webmcp-testing activé, ou un navigateur ultérieur avec une prise en charge native.
• document.modelContext doit être présent. Quand il est absent, Studio n'enregistre rien et le tableau de bord reste inchangé.
• Un vrai contexte de navigation. Cela ne marche pas en headless ; l'agent pilote l'onglet ouvert et vivant.
• Aucun changement de configuration ni de CSP du côté de Studio. La Permissions-Policy tools de WebMCP vaut self par défaut, ce qui correspond exactement au cas de même origine de Studio, donc il n'y a rien à accorder.

L'activer

Les outils pour agents sont désactivés par défaut. Active-les avec l'option sur la commande studio :

verbatra studio --expose-agent-tools

Ou définis la solution de repli par l'environnement :

VERBATRA_STUDIO_AGENT_TOOLS=1 verbatra studio

L'option et la variable d'environnement se résolvent exactement comme --allow-spend : 1, true, yes ou on (sans distinction de casse) compte pour activé, et l'option de la CLI l'emporte sur la variable. Si aucune des deux n'est donnée, aucun outil n'est enregistré. Voir verbatra studio pour toutes les options.

Ouvre ensuite l'URL loopback affichée dans ton navigateur compatible WebMCP. L'agent présent sur cet onglet découvre les outils enregistrés et peut les appeler.

Le catalogue d'outils

Avec l'option activée, Studio enregistre treize outils, un par action du tableau de bord. Sans --allow-spend, il en enregistre onze : les deux outils de dépense sont entièrement omis. Les noms d'outils sont préfixés et utilisent des tirets bas (par exemple verbatra_project_snapshot).

Outils de lecture (dix)

Ils inspectent l'état du projet sans rien changer. Ils sont marqués en lecture seule.

Outil d'écriture (un)

verbatra_translation_editEntry modifie sur place la valeur d'une locale. Il passe par le même contrôle d'intégrité que toute autre écriture verbatra : une valeur qui échoue à l'une de ses vérifications est rejetée et rien n'est écrit. Une modification acceptée écrit le fichier de locale et fait avancer l'entrée de verrou de la clé, exactement comme une modification depuis le tableau de bord. Modifier n'exige aucune option de dépense ; cela ne touche que tes fichiers locaux et n'appelle jamais de fournisseur.

Outils de dépense (deux)

Ceux-ci appellent un fournisseur de traduction et ne sont enregistrés que si Studio tourne aussi avec --allow-spend :

• verbatra_translation_retranslateEntry : retraduit une clé et une locale.
• verbatra_translation_translatePending : traduit tout ce qui est en attente à cet instant.

Tous deux font passer leurs résultats par le contrôle d'intégrité avant que quoi que ce soit n'atteigne le disque, et tous deux sont soumis aux limites de débit déjà en place dans Studio (retraduction à 20 par minute glissante, traduction de l'attente à 5 par minute glissante, plus un garde contre les appels concurrents). Sans --allow-spend, ils sont absents du jeu d'outils et le serveur n'enregistre même pas les points de terminaison sous-jacents, donc une dépense que tu n'as pas accordée au démarrage reste hors de portée d'un agent.

L'avis de mode dégradé

L'enregistrement a trois issues possibles, et une seule est un problème.

Rien de tenté, rien de signalé. Quand document.modelContext est absent (un navigateur sans WebMCP, ou Chrome sans le flag) ou quand tu n'as pas activé l'exposition, Studio ne tente aucun enregistrement. Le tableau de bord reste inchangé et la console reste muette. C'est le no-op prévu, pas un échec.

Onze outils et aucun avis. Sans --allow-spend, Studio tente onze enregistrements plutôt que treize : les deux outils de dépense sont écartés avant même d'être tentés. Onze outils est le compte sain d'une session sans dépense, leur absence est donc l'état attendu et ne déclenche jamais d'avis.

L'avis. Si Studio a tenté un enregistrement et que le navigateur l'a rejeté, le tableau de bord affiche un avertissement en haut de la zone de contenu, sur toutes les vues :

Agent tools degraded: 2 of the agent tool registrations failed with SecurityError. The dashboard itself is unaffected. The browser console lists every failing tool.

Le décompte et le nom d'erreur sont les vrais, ceux de cette passe. L'avis n'a pas de commande de fermeture et reste affiché tant que vit la page. Recharger l'onglet lance une nouvelle passe d'enregistrement, puisque l'état n'est gardé qu'en mémoire.

Ce qui fonctionne encore en mode dégradé

Un outil qui échoue n'annule jamais ceux qui suivent, donc tout outil bien enregistré reste appelable et la surface est le plus souvent partiellement utilisable plutôt que hors service. Le tableau de bord n'est pas touché : l'interface humaine, les RPC et chaque contrôle de capacité se comportent exactement comme si l'exposition était coupée, et aucun fichier de locale n'est affecté.

Lire la console

Studio écrit une seule ligne agrégée au niveau erreur, et non une ligne par outil, parce qu'une cause commune fait échouer tous les outils de façon identique :

Verbatra agent tools: 2 of 11 tool registrations failed. verbatra_status_diff (SecurityError: ...); verbatra_key_value (SecurityError: ...)

La première phrase indique combien des enregistrements tentés ont échoué, et sur combien de tentatives. Chaque outil en échec suit ensuite sous la forme name (ErrorName: message), séparés par des points-virgules. Le nom d'erreur identifie la cause : c'est le name de la valeur avec laquelle le navigateur a rejeté, en général une DOMException comme SecurityError ou InvalidStateError.

Une passe qui n'a jamais atteint la boucle par outil signale une ligne différente et ne déclenche pas l'avis :

Verbatra agent tools: registration did not start (TypeError: Failed to fetch).

Cela veut dire que l'appel d'instantané du projet qui décide si l'exposition est activée a échoué au chargement, donc aucun outil n'a été tenté.

Ce que tu peux faire

Aucun réglage de Studio ne corrige un enregistrement rejeté, car le rejet vient du navigateur. En pratique :

• Lis d'abord le nom d'erreur dans la console. Il nomme la cause plus précisément que l'avis.
• Recharge l'onglet. L'enregistrement s'exécute une fois par chargement de page, donc un rejet passager disparaît.
• Revérifie les prérequis du navigateur ci-dessus. Un flag manquant ou un navigateur sans WebMCP produit le no-op silencieux, jamais cet avis ; si tu vois l'avis, c'est que la surface a bien démarré.
• Continue d'utiliser les outils qui se sont enregistrés, ou travaille dans le tableau de bord, qui n'est de toute façon pas affecté.

Modèle de sécurité

Garde ces points en tête avant d'activer les outils pour agents.

• Désactivés par défaut. Tu choisis explicitement de les activer avec --expose-agent-tools (ou VERBATRA_STUDIO_AGENT_TOOLS).
• La dépense exige les deux options. Les deux outils de dépense n'apparaissent que si tu passes à la fois --expose-agent-tools et --allow-spend. Aucune des deux options n'implique l'autre. Les outils de lecture et d'écriture ne dépensent rien.
• Aucune exposition réseau nouvelle. Chaque appel d'outil emprunte le même RPC loopback authentifié que le tableau de bord. Studio n'écoute toujours que sur 127.0.0.1, et le token de session du navigateur authentifie toujours chaque requête.
• Les chaînes traduisibles ne sont pas de confiance. Les outils qui peuvent renvoyer du texte issu du projet (chaînes de locale, noms de clés, termes de glossaire, sujets de commits, jetons de placeholders) marquent leur contenu comme non fiable, pour qu'un agent consommateur traite ces valeurs comme des données et non comme des instructions.

Le risque de dépense accepté

Disons-le franchement : avec --allow-spend et --expose-agent-tools activés tous les deux, un agent autonome peut déclencher une dépense fournisseur sans confirmation humaine à chaque clic. Studio n'ajoute pas de boîte de dialogue d'approbation par appel : le serveur ne peut pas distinguer un appel venu d'un agent d'un clic humain dans la même session, une telle boîte donnerait donc une assurance trompeuse et viderait la fonctionnalité de son sens. Les limites de débit ci-dessus bornent toujours le coût, mais un agent peut boucler tout seul jusqu'à ce plafond.

Active la dépense pilotée par un agent en connaissance de cause. Si tu veux seulement qu'un agent inspecte l'état et corrige des entrées à la main, lance Studio sans --allow-spend : les outils pour agents fonctionnent pleinement dans ce mode lecture et modification, et aucun outil ne peut atteindre un fournisseur.

Et ensuite

• Réviser les traductions dans Studio : le même flux de travail, mené par une personne.
• verbatra studio : toutes les options et le contrat de démarrage.
• Sûreté de la traduction : le contrôle d'intégrité par lequel passe chaque modification et chaque retraduction.