Référence Conductor
Verbes CLI, méthodes JSON-RPC, champs, événements, clés de configuration et codes de sortie du plan de contrôle Paneflow Conductor.
Cette page est la référence compacte de Conductor. Elle nomme la surface publique et les champs qu'un script ou un LLM peut utiliser de façon fiable.
Verbes CLI
| Verbe | Méthode principale | Usage |
|---|---|---|
ps [--json] | fleet.list | Liste les agents détectés dans les workspaces |
status <target> [--json] | surface.status | Lit l'état agent d'une pane |
watch [--surface <sel>] [--type <event>] | events.subscribe | Stream les événements de cycle de vie et les changements de surface |
read <target> | surface.read | Lit le scrollback d'une pane |
send <target> <text> | surface.send_text | Prépare ou soumet du texte dans une pane |
wait --match <sel> | surface.read, flux d'événements en mode idle | Bloque jusqu'à l'état idle, une regex ou les deux |
up <file> | orchestration workspace | Crée un workspace d'agents déclaratif |
flow run <file> | orchestration flow | Lance un pipeline multi-agent |
ls, search, focus, key | méthodes scripting | Utiles quand l'état conductor ne suffit pas |
Les lectures sont autorisées par défaut. Les écritures comme send --submit, key et les étapes de flow qui soumettent du texte exigent le scripting gate ou le mode AI free access.
Sélecteurs
| Sélecteur | Exemple | Notes |
|---|---|---|
| Id numérique | paneflow status 42 | Id exact de pane |
| Nom | paneflow status backend | Meilleur sélecteur pour les workflows conductor |
cmdline:<substr> | paneflow read cmdline:claude | Utile mais moins portable qu'un nom de pane |
cwd:<path> | paneflow read cwd:/home/me/app | Bon choix pour les scripts liés à un repo |
Un sélecteur qui ne matche rien ou plusieurs panes sort avec le code 3, sauf pour les commandes qui acceptent explicitement plusieurs matches comme les sends broadcast ou wait --any et wait --all.
fleet.list
paneflow ps --json retourne un tableau agents.
| Champ | Sens |
|---|---|
pid | Id de processus agent, ou null pour une détection scan-only |
tool | Famille d'agent comme claude, codex, opencode ou gemini |
state | thinking, waiting_for_input, finished, errored, stalled, idle ou unknown_running |
hooked | true quand Paneflow reçoit les événements de hook |
reason | Raison de détection, dont no_hook pour les processus non hookés |
surface_id | Id de pane quand résolu |
surface_name | Nom de pane quand présent |
workspace | Index du workspace |
active_tool_name | Outil actuellement exécuté par l'agent, si reporté |
message | Question ou permission en attente, si reportée |
last_result | Résumé du dernier tour, quand le hook le fournit |
waiting_ms | Millisecondes passées en attente d'entrée |
idle_ms | Millisecondes depuis la dernière activité observée |
Une flotte vide retourne {"agents":[]} avec le code de sortie 0.
surface.status
paneflow status <target> --json retourne le statut d'une pane.
| Champ | Sens |
|---|---|
surface_id | Id de pane |
state | Même vocabulaire que fleet.list |
hooked | Indique si le suivi de cycle de vie est actif |
tool | Famille d'agent, si détectée |
active_tool_name | Outil actuellement exécuté, si reporté |
message | Question ou permission en attente, si reportée |
last_result | Résumé du dernier tour, quand disponible |
waiting_ms | Millisecondes passées en attente d'entrée |
idle_ms | Millisecondes depuis la dernière activité observée |
output_generation | Compteur monotone qui avance quand la sortie de pane change |
Une pane sans agent actif retourne un état idle au lieu d'une erreur.
surface.read
paneflow read <target> retourne du texte de terminal. Par défaut, la sortie est enveloppée dans <untrusted_terminal_output> pour qu'un LLM puisse l'inspecter sans la traiter comme des instructions. Utilisez --raw seulement pour des scripts humains de confiance.
Les champs utiles en mode JSON incluent text, lines, total_lines, eof et output_generation.
events.subscribe et watch
paneflow watch est du JSON délimité par lignes. Il peut émettre :
| Type d'événement | Sens |
|---|---|
ai.session_start | Une session agent démarre |
ai.prompt_submit | Un prompt est soumis |
ai.tool_use | L'agent invoque un outil |
ai.notification | L'agent pose une question ou demande une permission |
ai.stop | Un tour se termine |
ai.exit | Le processus agent sort |
ai.session_end | La session se ferme |
surface_changed | Le output_generation de la pane a avancé |
Les frames de contrôle sont aussi valides :
| Frame | Sens |
|---|---|
subscribed | Subscription acceptée |
heartbeat | Frame keepalive |
dropped | Le subscriber a pris du retard et des événements ont été supprimés |
Quand un client reçoit dropped, il doit se resynchroniser avec paneflow ps --json ou paneflow status <target> --json.
wait
wait --idle utilise le flux d'événements quand il est disponible et bascule proprement en fallback si nécessaire. wait --pattern poll le scrollback récent toutes les 500 ms et scanne les 500 dernières lignes.
| Mode | Exemple | Usage |
|---|---|---|
| Idle | paneflow wait --match reviewer --idle --timeout 600 | Continuer après l'arrêt du travail agent |
| Pattern | paneflow wait --match backend --pattern '^DONE:' --timeout 300 | Continuer après une ligne sentinelle |
| Idle plus pattern | paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600 | Exiger une pane stable et un marqueur |
| Any ou all | paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all | Coordonner plusieurs panes en mode pattern |
Les timeouts sortent avec le code 4.
Clés de configuration
| Clé | Défaut | Sens |
|---|---|---|
ai_unrestricted | false | Autorise l'automation IA de confiance à soumettre quand activé |
ai_injection_fence | true | Enveloppe la sortie terminal pair comme texte non fiable |
agent_stall_threshold_secs | défaut app | Marque comme stalled les tours silencieux encore en cours |
Codes de sortie
| Code | Sens |
|---|---|
0 | Succès |
1 | Échec runtime |
2 | Erreur d'usage CLI |
3 | Cible introuvable ou ambiguë |
4 | Timeout de wait |