Conductor-Referenz
CLI-Verben, JSON-RPC-Methoden, Felder, Events, Konfigurationsschlüssel und Exit-Codes der Paneflow Conductor Steuerungsebene.
Diese Seite ist die kompakte Referenz für Conductor. Sie benennt die öffentliche Oberfläche und die Felder, auf die sich ein Skript oder LLM verlassen kann.
CLI-Verben
| Verb | Primäre Methode | Nutzung |
|---|---|---|
ps [--json] | fleet.list | Erkannte Agents über Workspaces listen |
status <target> [--json] | surface.status | Agent-Status einer Pane lesen |
watch [--surface <sel>] [--type <event>] | events.subscribe | Lifecycle-Events und Surface-Änderungen streamen |
read <target> | surface.read | Pane-Scrollback lesen |
send <target> <text> | surface.send_text | Text in einer Pane vorbereiten oder absenden |
wait --match <sel> | surface.read, Eventstream im Idle-Modus | Bis Idle-State, Regex oder beidem blockieren |
up <file> | Workspace-Orchestrierung | Deklarativen Agent-Workspace erstellen |
flow run <file> | Flow-Orchestrierung | Multi-Agent-Pipeline starten |
ls, search, focus, key | Scripting-Methoden | Niedrigere Pane-Automation nutzen |
Leseoperationen sind standardmäßig erlaubt. Schreiboperationen wie send --submit, key und Flow-Schritte, die Text absenden, brauchen den Scripting-Gate oder AI free access.
Selektoren
| Selektor | Beispiel | Hinweise |
|---|---|---|
| Numerische id | paneflow status 42 | Exakte Pane-Id |
| Name | paneflow status backend | Bester Selektor für Conductor-Workflows |
cmdline:<substr> | paneflow read cmdline:claude | Nützlich, aber weniger portabel als ein Pane-Name |
cwd:<path> | paneflow read cwd:/home/me/app | Gut für repo-bezogene Skripte |
Ein Selektor, der nichts oder mehrere Panes trifft, beendet mit Code 3, außer Befehle erlauben mehrere Treffer ausdrücklich, etwa Broadcast-Sends oder wait --any und wait --all.
fleet.list
paneflow ps --json gibt ein agents Array zurück.
| Feld | Bedeutung |
|---|---|
pid | Agent-Prozess-ID, oder null für scan-only Erkennung |
tool | Agent-Familie wie claude, codex, opencode oder gemini |
state | thinking, waiting_for_input, finished, errored, stalled, idle oder unknown_running |
hooked | true, wenn Paneflow Lifecycle-Hook-Events empfängt |
reason | Erkennungsgrund, inklusive no_hook für nicht gehookte Prozesse |
surface_id | Pane-Id, wenn aufgelöst |
surface_name | Pane-Name, wenn vorhanden |
workspace | Workspace-Index |
active_tool_name | Aktuell laufendes Tool im Agent, wenn gemeldet |
message | Wartende Frage oder Permission-Text, wenn gemeldet |
last_result | Zusammenfassung des letzten Turns, wenn der Hook sie liefert |
waiting_ms | Millisekunden in Wartezustand |
idle_ms | Millisekunden seit der letzten beobachteten Aktivität |
Eine leere Flotte ist {"agents":[]} mit Exit-Code 0.
surface.status
paneflow status <target> --json gibt einen Pane-Status zurück.
| Feld | Bedeutung |
|---|---|
surface_id | Pane-Id |
state | Dieselbe State-Vokabel wie fleet.list |
hooked | Ob Lifecycle-Tracking aktiv ist |
tool | Agent-Familie, wenn erkannt |
active_tool_name | Aktuell laufendes Tool, wenn gemeldet |
message | Wartende Frage oder Permission-Text, wenn gemeldet |
last_result | Zusammenfassung des letzten Turns, wenn verfügbar |
waiting_ms | Millisekunden in Wartezustand |
idle_ms | Millisekunden seit der letzten beobachteten Aktivität |
output_generation | Monotoner Zähler, der bei Pane-Ausgabe fortschreitet |
Eine Pane ohne aktiven Agent gibt einen Idle-State statt eines Fehlers zurück.
surface.read
paneflow read <target> gibt Terminaltext zurück. Standardmäßig wird Ausgabe in <untrusted_terminal_output> verpackt, damit ein LLM sie lesen kann, ohne sie als Anweisung zu behandeln. Nutzen Sie --raw nur für vertrauenswürdige Mensch-Skripte.
Nützliche Felder im JSON-Modus sind text, lines, total_lines, eof und output_generation.
events.subscribe und watch
paneflow watch ist newline-delimited JSON. Es kann ausgeben:
| Event-Typ | Bedeutung |
|---|---|
ai.session_start | Eine Agent-Session beginnt |
ai.prompt_submit | Ein Prompt wird gesendet |
ai.tool_use | Der Agent ruft ein Tool auf |
ai.notification | Der Agent stellt eine Frage oder fordert Permission an |
ai.stop | Ein Turn endet |
ai.exit | Der Agent-Prozess beendet sich |
ai.session_end | Die Session schließt |
surface_changed | output_generation der Pane ist fortgeschritten |
Kontrollframes sind ebenfalls gültig:
| Frame | Bedeutung |
|---|---|
subscribed | Subscription bestätigt |
heartbeat | Keepalive-Frame |
dropped | Der Subscriber lag zurück und Events wurden verworfen |
Wenn ein Client dropped erhält, sollte er mit paneflow ps --json oder paneflow status <target> --json resynchronisieren.
wait
wait --idle nutzt den Eventstream, wenn er verfügbar ist, und fällt bei Bedarf sicher zurück. wait --pattern pollt aktuellen Scrollback alle 500 ms und scannt die letzten 500 Zeilen.
| Modus | Beispiel | Nutzung |
|---|---|---|
| Idle | paneflow wait --match reviewer --idle --timeout 600 | Nach Ende der Agent-Arbeit fortfahren |
| Pattern | paneflow wait --match backend --pattern '^DONE:' --timeout 300 | Nach einer Sentinel-Zeile fortfahren |
| Idle plus pattern | paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600 | Stabile Pane und Marker verlangen |
| Any oder all | paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all | Mehrere Panes im Pattern-Modus koordinieren |
Timeouts enden mit Code 4.
Konfigurationsschlüssel
| Schlüssel | Standard | Bedeutung |
|---|---|---|
ai_unrestricted | false | Erlaubt vertrauenswürdiger KI-Automation das Absenden, wenn aktiv |
ai_injection_fence | true | Verpackt Peer-Terminalausgabe als nicht vertrauenswürdigen Text |
agent_stall_threshold_secs | App-Default | Markiert stille laufende Turns als stalled |
Exit-Codes
| Code | Bedeutung |
|---|---|
0 | Erfolg |
1 | Runtime-Fehler |
2 | CLI-Nutzungsfehler |
3 | Ziel nicht gefunden oder mehrdeutig |
4 | wait Timeout |