Que fait PTY-Agent ?
PTY-Agent est un agent d'interaction pour programmes en ligne de commande interactifs qui communique en bidirectionnel avec des programmes CLI via subprocess ou pseudo-terminal (PTY).
Principe : un processus démon s'exécute en arrière-plan, reçoit les commandes de l'utilisateur et les transmet au programme CLI correspondant.
Le programme se trouve dans app.py, exécution : python app.py ...
Quand l'utiliser
- En dernier recours lorsqu'il est nécessaire de dialoguer en continu avec un programme interactif (REPL, débogueur, serveur, compilation) — envoyer une entrée et attendre une sortie spécifique (invite) avant de continuer. Mais si un script suffit, ne pas utiliser PTY-Agent.
- Le processus peut se bloquer ou s'exécuter longtemps — nécessité de vérifier régulièrement son état.
- Le sous-processus peut planter — besoin de détecter le crash en temps réel.
- Tests de simulation d'interactions utilisateur.
Quand ne pas l'utiliser
- Tâches non interactives.
- Cas où un script suffit.
- Interfaces GUI, navigateurs, programmes TUI complexes.
Aide-mémoire des commandes
| Commande | Utilisation | Options typiques | Exemple |
|---|---|---|---|
start/stop | Démarrer/arrêter manuellement le démon ; le démarrage exec suffit généralement. | ||
exec <nouvel-id-session> <options> | Exécuter une commande pour lancer une session | -c "<commande>" (obligatoire), -t "<regex>", --timeout <secondes>, --cwd <chemin> | exec id_py -c "python -i" -t ">>>" |
send <id-session> "<contenu>" [options] | Envoyer une entrée à une session en cours | -t "<regex>", --timeout <secondes> | send id_py "print(1)" -t ">>>" |
read <id-session> [options] | Lire la sortie d'une session | --lines, --grep | read myid --lines 10 |
list | Lister toutes les sessions | ||
kill <id-session> | Terminer une session | ||
events <id-session> [options] | Voir les événements d'une session | --last <N>, `--since <iso-datetime | HH:MM>` |
closewin <id-session> <identifiant-fenêtre> | Fermer une fenêtre GUI ; <identifiant-fenêtre> supporte décimal ou hexadécimal 0x |
Conditions de retour de la commande send
| Mode | Condition | Information renvoyée |
|---|---|---|
| Avec trigger | Correspondance à la regex | Sortie incrémentale |
| Avec idle-timeout | Timeout d'inactivité | Sortie incrémentale |
| Avec timeout | Atteinte du timeout | Sortie incrémentale |
| Aucun | Atteinte du timeout par défaut | Sortie incrémentale |
| Détection fenêtre GUI non fermée | Fenêtre GUI détectée (subprocess peut ne pas être disponible) | Infos fenêtre GUI + sortie incrémentale |
| Crash du processus | Événement associé + sortie incrémentale | |
| Fin du programme | Sortie incrémentale |
Remarque : Utiliser efficacement la fonction de conditions de retour du programme, en mettant à jour rapidement les conditions (notamment -t) en fonction du résultat du programme. Éviter les sleep dans le terminal, éviter d'enchaîner send puis read inutilement.
Utilisation de exec
python app.py exec <id-session> <options>
Options similaires à send. Options spécifiques :
-c "<commande>"(obligatoire) Commande à exécuter, requis.--shell <shell>Supportecmd/powershell/pwsh/bash(PowerShell par défaut, bascule automatique vers CMD si non supporté) ; configurable uniquement au lancementexec.--ptyActive le pseudo-terminal complet (ne supporte pas|,&&, etc.)--force-pty-modeIgnore la détection des opérateurs shell en mode--pty
--cwd <chemin>Répertoire de travail du sous-processus ; par défaut, celui de l'appelant (client). À spécifier si différent.
Utilisation de send
python app.py send <id-session> "<contenu>" [options]
Options
-t/--trigger "<regex>"Correspondance regex--newline— Vérifier la condition de trigger seulement après un saut de ligne, combiné avec-t
--timeout <secondes>Timeout d'attente (120s par défaut)--idle-after-first-outputDémarrer la détection d'inactivité seulement après la première sortie, combiné avec--idle-timeout- Remarque : Utiliser efficacement la fonction de conditions de retour du programme, en mettant à jour rapidement les conditions (notamment
-t) en fonction du résultat du programme. Éviter lessleepdans le terminal, éviter d'enchaînersendpuisreadinutilement.
--idle-timeout <secondes>Timeout d'inactivité : déclenché si aucune sortie dans le délai imparti.--fullRenvoyer toutes les données du terminal (volumineux, privilégier--lines N).--json-escapingMode d'échappement JSON : échappe<contenu>en JSON (\\ \" \n \t \r \uXXX ...), recommandé pour l'envoi de contenu multiligne.
<contenu> est automatiquement suivi d'un saut de ligne.
Pas de paramètre --input.
Règles de traitement des guillemets (niveau ligne de commande)
- cmd : utiliser
\"imbriqué :-c "python -c \"print(1)\"" - PowerShell/Pwsh : guillemets simples à l'extérieur, guillemets doubles à l'intérieur :
-c 'python -c "print(1)"'
Utilisation de read
python app.py read <id-session> [options]
Options :
--lines <N>Dernières N lignes--lines debut:finPlage de lignes--grep "<regex>"Filtre regex--offset <octets>Lecture incrémentale--fullRenvoyer toutes les données du terminal (volumineux, privilégier--lines N)
Utilisation complète de events
python app.py events <id-session> [options]
Options :
--last N--since <iso-datetime|HH:MM>--until <iso-datetime|HH:MM>
Options globales/générales
--keep-ansiConserver les codes de contrôle--colorActiver la sortie couleur dans le terminal--output-by-natural-languageSortie en langage naturel--encoding <encodage>Encodage du terminal ; en cas de caractères illisibles, définirutf-8/gbk/gb2312/gb18030/big5--no-debugDésactiver la sortie de débogage dans la réponse (arborescence des processus/fenêtres GUI/événements)--show-config [CLÉ]Afficher la configuration actuelle de l'appel--default <CLÉ> <VALEUR>Surcharger temporairement la configuration par défaut (clés possibles :output-by-natural-language/timeout/newline/keep-ansi/encoding/debug,<VALEUR>est la valeur ouon/off)
Format de sortie
- Mode JSON (par défaut) — stdout ne produit que du JSON, un objet JSON par ligne. Toutes les réponses non liées aux commandes (infos de démarrage/arrêt du démon, requêtes de configuration, texte d'aide, avertissements) sont également au format JSON :
- Réponse de commande :
{"type": "result", ...}/{"type": "ok", ...}/{"type": "error", ...} - Info démon :
{"type": "info", "message": "[pty-agent] Démon démarré (port 12345)"} - Requête de configuration :
{"type": "config", "content": "Configuration actuelle de l'appel:\n ..."} - Texte d'aide :
{"type": "help", "content": "usage: pty-agent ..."} - Avertissement :
{"type": "warning", "message": "..."}
- Réponse de commande :
- Mode langage naturel — activé avec
--output-by-natural-language
Exemples de scénarios
Surveillance de processus long + lecture intermédiaire + terminaison
app.py exec srv -c "python server.py" --idle-timeout 3 # Lancement, idle-timeout pour retour rapide après première sortie
app.py read srv --lines 20 # Consultation des 20 dernières lignes en cours
app.py read srv --offset 1024 # Lecture incrémentale (depuis le dernier offset)
app.py read srv --grep "ERROR" # Voir uniquement les lignes d'erreur
app.py kill srv # Terminer quand on n'en a plus besoin
Détection de crash de processus
app.py exec job -c "python worker.py" --idle-timeout 5 # Lancement, idle-timeout en attente de sortie
# Si le processus plante, la réponse contient trigger.reason="ended", program.exit_code non nul, error_message avec info de crash
app.py events job --last 10 # Voir les détails de l'événement de crash (type process_crash)