ii999/agentenv

Que fait agentenv ?

agentenv lit un fichier de configuration TOML local qui contient des valeurs ordinaires et des références à des identifiants. Les valeurs des identifiants résident dans une variable d'environnement, le gestionnaire de mots de passe de la plateforme ou une commande externe — jamais dans le fichier. L'interface en ligne de commande lit les valeurs, édite le fichier avec des écritures validées préservant le format, et lance des processus cibles avec les valeurs sélectionnées injectées dans un environnement temporaire.

Confirmez que l'interface en ligne de commande est disponible avec command -v agentenv avant de l'utiliser. Si elle est absente, dites-le et arrêtez-vous ; ne reconstituez pas son comportement en lisant le fichier de configuration directement.

Règles strictes

• N'imprimez, ne journalisez, ne persistez et ne résumez jamais une valeur d'identifiant résolue. Ne lancez pas agentenv run avec une cible choisie pour révéler son propre environnement — env, printenv, set, sh -c 'echo $VAR', ou écrire l'environnement dans un fichier sont tous des violations.
• N'écrivez jamais une valeur secrète dans le fichier de configuration. set est destiné aux valeurs ordinaires ; credential add écrit une définition uniquement ; credential set est le seul chemin qui stocke une valeur, et il la stocke dans le gestionnaire de mots de passe de la plateforme, pas dans le fichier.
• Si un profil, une entrée, un champ ou un identifiant est manquant, signalez-le explicitement. Ne devinez pas un nom de champ, ne changez pas silencieusement de profil et ne substituez pas un autre identifiant.
• Lisez la configuration via l'interface en ligne de commande, pas en ouvrant le fichier TOML, afin que la sélection de profil, l'indirection d'identifiant et la validation s'appliquent.
• Après que credential fill a écrit une valeur dans un champ de navigateur, ne lisez pas ce champ en retour, n'évaluez pas sa valeur et ne prenez pas de capture d'écran qui la montre. Le résultat du remplissage est la seule chose que vous pouvez rapporter.

Lecture de la configuration

Travaillez de haut en bas ; sautez les étapes déjà effectuées dans cette session.

1. agentenv project status --json — découvrez le fichier projet le plus proche et son état de confiance avant de lire une configuration dépendante du profil. Son rapport est écrit sur la sortie standard même quand il se termine avec le code 5 ou 6 ; un code de sortie 2 laisse la sortie standard vide.
2. agentenv list --json — découvrez les profils et les entrées. agentenv list --profiles liste les noms de profils sans en sélectionner un.
3. agentenv show <entry> --json — inspectez une entrée inconnue avant de l'utiliser. Les champs d'identifiant apparaissent comme un membre reference (credential://<name> ou credential://<name>?as=<ENV>), jamais comme une valeur.
4. agentenv get <path> — lisez une valeur scalaire ordinaire. Utilisez --json pour un tableau ou une table. La lecture d'un champ d'identifiant retourne la chaîne de référence, pas le secret.
5. agentenv find <needle> --json — recherchez dans les noms d'entrées, les noms de champs, les descriptions et les valeurs textuelles quand vous ne savez pas où se trouve quelque chose. Ajoutez --all-profiles pour chercher dans tous les profils.

Les chemins sont des segments de champ séparés par des points dans le profil sélectionné, par exemple llm.model. Mettez entre guillemets un segment contenant une ponctuation ou des espaces : servers."my host".port. Le profil ne fait pas partie du chemin ; sélectionnez-le avec --profile <NAME> (précédence : --profile, puis AGENTENV_PROFILE, puis l'épingle du fichier projet de confiance, puis default_profile dans le fichier). Cela s'applique aux lectures, run, set et unset. --create-profile nécessite un --profile explicite et n'utilise jamais l'épingle.

Configuration étendue au projet

agentenv découvre le fichier .agentenv.toml régulier le plus proche en remontant du répertoire de travail vers la racine du système de fichiers. Le fichier a un schéma fermé, uniquement pour la sélection : version = 1, un profile optionnel non vide, et des tables [requires.<entry>] optionnelles avec une reason non vide et des fields optionnelles relatives à l'entrée qui, lorsqu'elles sont présentes, sont non vides. Il est limité à 64 Ko et ne peut pas contenir de valeurs, de définitions d'identifiants, de tables inject ou de chaînes credential://.

Les fichiers projet sont inactifs jusqu'à ce que leur contenu exact soit approuvé. Utilisez agentenv project status, agentenv project allow et agentenv project revoke pour inspecter, approuver et supprimer l'approbation. L'approbation est conservée dans le répertoire d'état de l'utilisateur, en dehors du dépôt ; la modification du fichier le rend à nouveau non fiable. Un fichier non fiable n'affecte aucune commande ordinaire, à l'exception d'une notification sur la sortie d'erreur.

Utilisez --no-project, ou un AGENTENV_NO_PROJECT non vide, pour contourner la découverte pour une commande en dehors du groupe project. Le contournement ne s'applique jamais à project status, project allow ou project revoke, qui découvrent toujours le fichier le plus proche.

project status --json écrit délibérément son rapport sur la sortie standard avec le code de sortie 5 pour un état de projet indisponible, invalide ou non fiable, et avec le code de sortie 6 lorsque les exigences ne sont pas satisfaites ou ne peuvent pas être vérifiées. C'est l'exception à la règle habituelle de sortie standard vide sur un échec JSON. Le code de sortie 2 couvre les erreurs de configuration, y compris les erreurs de validation du fichier projet, et laisse la sortie standard vide pour cette commande.

Exécution d'une commande nécessitant des identifiants

Utilisez run avec un ou plusieurs drapeaux --with <entry> et la cible après -- :

agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync

Chaque entrée --with apporte ses références d'identifiants et sa table inject (qui mappe les noms d'environnement aux champs ordinaires de cette entrée). Un identifiant s'injecte sous son nom inject_as sauf si la référence porte une surcharge ?as=<ENV>. Pour connaître les noms d'environnement qu'une cible recevra, lisez inject_as depuis agentenv credential list --json et les membres inject et reference depuis agentenv show <entry> --json.

L'entrée/sortie standard et d'erreur de la cible transitent inchangées et son code de sortie est retourné. Les injections conflictuelles (deux sources ciblant un même nom d'environnement) s'interrompent avec le code de sortie 4 avant toute résolution ou lancement.

Ajoutez --pure pour lancer la cible avec un environnement minimal soigneusement sélectionné : une base de plateforme fixe (PATH, HOME, locale, AGENTENV_* et autres noms critiques pour le processus), plus les variables transportées explicitement avec --keep <NAME> répétable, plus les injections — rien d'autre de l'environnement appelant. Un nom conservé mais non défini dans le parent est signalé sur la sortie d'erreur et l'exécution continue. --pure filtre uniquement l'environnement de la cible ; ce n'est pas un bac à sable, et les appels agentenv imbriqués à l'intérieur de la cible résolvent toujours la même configuration. La résolution des identifiants n'est pas modifiée par --pure : le sous-processus d'un fournisseur command conserve l'environnement parent complet.

Écriture de la configuration

Utilisez ces commandes lorsque l'utilisateur demande d'enregistrer une configuration :

agentenv init                            # crée le fichier de configuration ; refuse d'écraser
agentenv set <path> <value>              # écrit une valeur ; crée les tables intermédiaires
agentenv set <path> <value> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "LLM par défaut."   # crée aussi l'entrée
agentenv set <path> <value> --profile dev --create-profile "Profil de développement."
agentenv unset <path>                    # supprime un champ ou une table

Chaque entrée nécessite une description ; la création d'une nouvelle entrée de premier niveau nécessite --description sur le même set. Un profil inconnu est une erreur, sauf si vous passez --create-profile avec un --profile explicite. Chaque écriture est d'abord validée sur l'ensemble du fichier et refusée si le résultat serait invalide, donc une écriture refusée laisse le fichier identique octet par octet — signalez le diagnostic plutôt que de réessayer des variations à l'aveugle.

La validation refuse les valeurs en texte clair dans les champs nommés (ou suffixés) token, password, secret, api_key ou private_key : ces champs doivent contenir une référence credential://. Lorsque l'utilisateur vous confie un secret à enregistrer, définissez-le et stockez-le comme un identifiant (section suivante), puis référencez-le.

Gestion des identifiants

agentenv credential list --json          # définitions + statut superficiel ; ne résout rien
agentenv credential check <name>         # résout un identifiant ; ne rapporte que la disponibilité
agentenv credential add <name> --description "<texte>" --provider env \
    --env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<texte>" --provider keychain \
    --service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<texte>" --provider command \
    --argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json  # ouvre une entrée locale ; attend son résultat

Ordre pour un nouvel identifiant : credential add la définition, puis pour le fournisseur keychain stockez la valeur avec credential set, puis référencez-la depuis un champ d'entrée comme credential://<name>. Les identifiants env et commande obtiennent leur valeur de leurs systèmes externes ; credential set ne s'applique pas à eux.

Pour une entrée locale du gestionnaire de mots de passe, lancez credential set <name> --input dialog --json sans PTY. Dites à l'utilisateur de saisir la valeur dans la fenêtre locale et d'enregistrer. Gardez la commande en cours d'exécution et attendez sa fin, y compris pendant les suspensions des sessions d'outil ; une fenêtre ouverte n'est pas un enregistrement terminé. N'inspectez, ne capturez, ne lisez et n'automatisez jamais la fenêtre d'entrée en direct ou le presse-papiers. L'utilisateur saisit et vérifie la valeur à cet endroit, et la commande ne retourne que des métadonnées de fin.

Continuez la tâche dépendante uniquement après un code de sortie 0 et un JSON status: "stored". status: "cancelled" signifie que l'entrée s'est terminée sans enregistrement confirmé ; signalez-le et arrêtez l'action dépendante. status: "failed" inclut un reason non secret ; signalez le diagnostic. store-unconfirmed signifie qu'une écriture a peut-être eu lieu, donc ne prétendez pas que la valeur précédente est inchangée et ne réessayez pas automatiquement. Les erreurs de démarrage/de configuration peuvent se terminer avant l'émission du JSON ; traitez un code de sortie non nul ou un résultat manquant comme un échec. Une sauvegarde déjà en cours se termine avant le retour de la commande ; une écriture confirmée rapporte stored même si l'utilisateur a demandé la fermeture pendant cette écriture.

La boîte de dialogue nécessite une session graphique sur la machine exécutant agentenv. Sur un hôte distant ou sans tête, expliquez cette limitation et demandez à l'utilisateur d'exécuter agentenv credential set <name> --input terminal lui-même dans le terminal de cet hôte, puis confirmez la fin. Ne substituez pas un PTY ou un tube d'entrée standard appartenant à l'Agent. Ne demandez jamais la valeur dans le chat et ne la placez pas dans un argv, une variable d'environnement, un tube de commande ou un fichier. L'entrée terminal prend en charge une bascule d'affichage locale, donc sa sortie écran doit rester en dehors des outils de l'Agent.

Préférez les fournisseurs keychain ou command pour une utilisation locale ; env expose la valeur à chaque processus héritant de l'environnement et convient à l'intégration continue.

Appairage Docker Compose

Conservez les paramètres non secrets dans .env. Injectez les identifiants uniquement pour le processus qui en a besoin, puis laissez Compose recevoir la variable injectée :

agentenv run --with llm -- docker compose up

services:
  app:
    image: alpine:3.20
    environment:
      - OPENAI_API_KEY

L'interpolation ${OPENAI_API_KEY} est également prise en charge par Compose. N'utilisez pas d'env_file: contenant des secrets ; cela persiste les identifiants dans un fichier.

Remplir un champ de navigateur avec un identifiant

Utilisez credential fill lorsqu'une page que vous pilotez a besoin d'un identifiant stocké dans un champ de saisie. Il écrit la valeur via le protocole de débogage du navigateur ; vous continuez à naviguer et à soumettre avec votre propre outil de navigateur.

agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
    --page-url <URL exacte de la page> --selector '<css du champ cible>' --json

Étapes :

1. Confirmez que --capabilities liste le backend cdp comme disponible. Votre navigateur doit exposer un point de terminaison de protocole Chrome DevTools en boucle locale (un Chromium démarré avec --remote-debugging-port et un --user-data-dir non par défaut, ou le point de terminaison que votre outil de navigateur utilise déjà). S'il n'y en a pas, dites-le ; ne lancez pas de navigateur et ne collez pas la valeur.
2. Naviguez vers la page avec votre outil de navigateur, puis passez l'URL exacte de la page et un sélecteur CSS qui correspond uniquement au champ cible. Ajoutez --page-match origin-path lorsque l'URL comporte des paramètres de requête volatils, --frame-selector pour chaque iframe sur le chemin du champ, et --context-index si la même URL est ouverte dans plusieurs contextes.
3. Fermez DevTools sur cet onglet et gardez le traçage, les screencasts, HAR et l'enregistrement vidéo désactivés pendant le remplissage ; agentenv échoue uniquement sur la fenêtre DevTools ouverte car les autres enregistreurs ne peuvent pas être détectés.
4. Exécutez la commande. Le succès imprime uniquement {"version":1,"backend":"cdp","effect":"field-filled"} ; le contenu précédent du champ a été remplacé et la page a reçu des événements d'entrée normaux. Continuez avec votre propre outil pour soumettre.

Seuls les identifiants qui autorisent l'utilisation environment peuvent être remplis ; la valeur doit être une seule ligne d'au plus 8 192 octets sans caractères de contrôle, de séparation de ligne ou de contrôle bidirectionnel (value-unsupported sinon). Un fournisseur de commande s'exécute sans terminal et son unique saut de ligne final est supprimé ; une sortie vide, NUL ou non UTF-8 du fournisseur est une erreur d'identifiant (code de sortie 4). L'opération entière, y compris une boîte de dialogue d'autorisation du gestionnaire de mots de passe au premier accès, s'exécute sous --timeout-ms (30 000 par défaut) ; augmentez-le lorsque l'utilisateur doit cliquer sur une telle boîte de dialogue. credential fill ne vérifie pas le champ, ne soumet pas le formulaire et ne connecte pas ; signalez l'effet, pas un succès que vous n'avez pas observé.

Raisons d'échec sur la sortie d'erreur (credential-fill: <reason>: <message>). Code de sortie 8, rien n'a changé : backend-unavailable, permission, connect-failed, version-unsupported, recording-conflict, context-absent, page-absent, page-ambiguous, frame-absent, frame-ambiguous, frame-invalid, target-absent, target-ambiguous, target-hidden, target-disabled, target-readonly, target-unfillable, target-changed, value-unsupported, timeout, cancelled. Code de sortie 11, le champ peut contenir la valeur : timeout, cancelled ou delivery-failed après que la valeur a été envoyée, et cleanup-unconfirmed après une valeur délivrée.

Exécution privilégiée

Lorsque la demande utilise une sudo-target configurée, lisez references/sudo-execution.md avant de planifier, vérifier, exécuter, créer ou faire pivoter cette cible.