Conductor reference
Paneflow Conductor 制御プレーンの CLI verbs、JSON-RPC methods、fields、events、config keys、exit codes。
このページは Conductor のコンパクトな reference です。公開 surface と、script や LLM が信頼できる fields を定義します。
CLI verbs
| Verb | Primary method | Use |
|---|---|---|
ps [--json] | fleet.list | workspaces 全体の検出済み agents を一覧 |
status <target> [--json] | surface.status | 1 つの pane の agent state を読む |
watch [--surface <sel>] [--type <event>] | events.subscribe | lifecycle events と surface changes を stream |
read <target> | surface.read | pane scrollback を読む |
send <target> <text> | surface.send_text | pane に text を準備または送信 |
wait --match <sel> | surface.read, idle mode では event stream | idle state、regex、またはその両方まで block |
up <file> | workspace orchestration | 宣言的 agent workspace を作成 |
flow run <file> | flow orchestration | multi-agent pipeline を実行 |
ls, search, focus, key | scripting methods | conductor state だけでは足りない時の低レイヤー pane automation |
読み取り操作はデフォルトで許可されています。send --submit、key、text を送信する flow step などの書き込みは、scripting gate または AI free access mode が必要です。
Selectors
| Selector | Example | Notes |
|---|---|---|
| Numeric id | paneflow status 42 | 正確な pane id |
| Name | paneflow status backend | conductor workflows に最適な selector |
cmdline:<substr> | paneflow read cmdline:claude | 便利ですが pane name より portable ではありません |
cwd:<path> | paneflow read cwd:/home/me/app | repo-scoped scripts に適しています |
何も match しない、または複数の pane に match する selector は code 3 で終了します。ただし broadcast sends、wait --any、wait --all のように複数 match を明示的に受け入れる command は例外です。
fleet.list
paneflow ps --json は agents array を返します。
| Field | Meaning |
|---|---|
pid | agent process id、scan-only detection では null |
tool | claude、codex、opencode、gemini などの agent family |
state | thinking、waiting_for_input、finished、errored、stalled、idle、unknown_running |
hooked | Paneflow が lifecycle hook events を受け取っている時 true |
reason | detection reason。unhooked processes では no_hook など |
surface_id | 解決できた場合の pane id |
surface_name | 存在する場合の pane name |
workspace | workspace index |
active_tool_name | agent 内で実行中の tool。報告される場合 |
message | 待機中の question または permission text。報告される場合 |
last_result | hook が提供する場合の last turn summary |
waiting_ms | 入力待ちに入ってからの milliseconds |
idle_ms | 最後に観測された activity からの milliseconds |
空のフリートは exit code 0 で {"agents":[]} です。
surface.status
paneflow status <target> --json は 1 つの pane status を返します。
| Field | Meaning |
|---|---|
surface_id | pane id |
state | fleet.list と同じ state vocabulary |
hooked | lifecycle tracking が有効かどうか |
tool | 検出された場合の agent family |
active_tool_name | 実行中の tool。報告される場合 |
message | 待機中の question または permission text。報告される場合 |
last_result | 利用可能な場合の last turn summary |
waiting_ms | 入力待ちに入ってからの milliseconds |
idle_ms | 最後に観測された activity からの milliseconds |
output_generation | pane output が変わると進む monotonic counter |
active agent がない pane は error ではなく idle state を返します。
surface.read
paneflow read <target> は terminal text を返します。デフォルトでは出力が <untrusted_terminal_output> で包まれるため、LLM はそれを instruction としてではなく inspect 対象として扱えます。--raw は trusted human scripts だけで使ってください。
JSON mode で有用な fields は text、lines、total_lines、eof、output_generation です。
events.subscribe と watch
paneflow watch は newline-delimited JSON です。次を emit できます。
| Event type | Meaning |
|---|---|
ai.session_start | agent session が始まる |
ai.prompt_submit | prompt が submit される |
ai.tool_use | agent が tool を呼び出す |
ai.notification | agent が質問または permission を要求する |
ai.stop | turn が終わる |
ai.exit | agent process が終了する |
ai.session_end | session が閉じる |
surface_changed | pane の output_generation が進んだ |
Control frames も有効です。
| Frame | Meaning |
|---|---|
subscribed | subscription acknowledged |
heartbeat | keepalive frame |
dropped | subscriber が遅れ、events が破棄された |
client が dropped を受け取ったら、paneflow ps --json または paneflow status <target> --json で resync してください。
wait
wait --idle は利用可能なら event stream を使い、必要なら安全に fallback します。wait --pattern は 500 ms ごとに最近の scrollback を poll し、最新 500 行を scan します。
| Mode | Example | Use |
|---|---|---|
| Idle | paneflow wait --match reviewer --idle --timeout 600 | agent が作業を止めた後に続行 |
| Pattern | paneflow wait --match backend --pattern '^DONE:' --timeout 300 | sentinel line の後に続行 |
| Idle plus pattern | paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600 | 安定した pane と marker の両方を要求 |
| Any or all | paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all | pattern mode で複数 panes を調整 |
Timeout は code 4 で終了します。
Config keys
| Key | Default | Meaning |
|---|---|---|
ai_unrestricted | false | 有効時、trusted AI automation に submit を許可 |
ai_injection_fence | true | peer terminal output を untrusted text として包む |
agent_stall_threshold_secs | app default | 無音の in-progress turns を stalled として mark |
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Runtime failure |
2 | CLI usage error |
3 | Target not found or ambiguous |
4 | wait timeout |