Referencia de Conductor
Verbos de CLI, métodos JSON-RPC, campos, eventos, claves de configuración y códigos de salida del plano de control Paneflow Conductor.
Esta página es la referencia compacta de Conductor. Nombra la superficie pública y los campos en los que puede confiar un script o LLM.
Verbos de CLI
| Verbo | Método principal | Uso |
|---|---|---|
ps [--json] | fleet.list | Lista agentes detectados en workspaces |
status <target> [--json] | surface.status | Lee el estado de agente de un panel |
watch [--surface <sel>] [--type <event>] | events.subscribe | Transmite eventos de ciclo de vida y cambios de superficie |
read <target> | surface.read | Lee el scrollback de un panel |
send <target> <text> | surface.send_text | Prepara o envía texto a un panel |
wait --match <sel> | surface.read, stream de eventos en modo idle | Bloquea hasta estado idle, una regex o ambos |
up <file> | orquestación de workspace | Crea un workspace declarativo de agentes |
flow run <file> | orquestación de flow | Ejecuta un pipeline multi-agente |
ls, search, focus, key | métodos de scripting | Automatización de paneles de menor nivel |
Las lecturas están permitidas por defecto. Escrituras como send --submit, key y pasos de flow que envían texto requieren el scripting gate o AI free access.
Selectores
| Selector | Ejemplo | Notas |
|---|---|---|
| Id numérico | paneflow status 42 | Id exacto de panel |
| Nombre | paneflow status backend | Mejor selector para workflows conductor |
cmdline:<substr> | paneflow read cmdline:claude | Útil pero menos portable que un nombre de panel |
cwd:<path> | paneflow read cwd:/home/me/app | Bueno para scripts de repo |
Un selector que no encuentra nada o encuentra varios paneles sale con código 3, salvo comandos que aceptan varias coincidencias explícitamente, como envíos broadcast o wait --any y wait --all.
fleet.list
paneflow ps --json devuelve un array agents.
| Campo | Significado |
|---|---|
pid | Id de proceso del agente, o null para detección scan-only |
tool | Familia de agente como claude, codex, opencode o gemini |
state | thinking, waiting_for_input, finished, errored, stalled, idle o unknown_running |
hooked | true cuando Paneflow recibe eventos de hooks de ciclo de vida |
reason | Razón de detección, incluido no_hook para procesos sin hooks |
surface_id | Id de panel cuando se resuelve |
surface_name | Nombre de panel cuando existe |
workspace | Índice de workspace |
active_tool_name | Herramienta actualmente ejecutada dentro del agente, si se informa |
message | Pregunta o permiso en espera, si se informa |
last_result | Resumen del último turno, si el hook lo proporciona |
waiting_ms | Milisegundos esperando entrada |
idle_ms | Milisegundos desde la última actividad observada |
Una flota vacía es {"agents":[]} con código de salida 0.
surface.status
paneflow status <target> --json devuelve el estado de un panel.
| Campo | Significado |
|---|---|
surface_id | Id de panel |
state | Mismo vocabulario de estado que fleet.list |
hooked | Si el seguimiento de ciclo de vida está activo |
tool | Familia de agente, cuando se detecta |
active_tool_name | Herramienta actualmente en ejecución, si se informa |
message | Pregunta o permiso en espera, si se informa |
last_result | Resumen del último turno, cuando está disponible |
waiting_ms | Milisegundos esperando entrada |
idle_ms | Milisegundos desde la última actividad observada |
output_generation | Contador monótono que avanza cuando cambia la salida del panel |
Un panel sin agente activo devuelve estado idle en vez de error.
surface.read
paneflow read <target> devuelve texto de terminal. Por defecto, la salida se envuelve en <untrusted_terminal_output> para que un LLM pueda inspeccionarla sin tratarla como instrucciones. Usa --raw solo para scripts humanos de confianza.
Campos útiles en modo JSON incluyen text, lines, total_lines, eof y output_generation.
events.subscribe y watch
paneflow watch es JSON delimitado por líneas. Puede emitir:
| Tipo de evento | Significado |
|---|---|
ai.session_start | Comienza una sesión de agente |
ai.prompt_submit | Se envía un prompt |
ai.tool_use | El agente invoca una herramienta |
ai.notification | El agente hace una pregunta o solicita permiso |
ai.stop | Termina un turno |
ai.exit | Sale el proceso del agente |
ai.session_end | Se cierra la sesión |
surface_changed | Avanzó el output_generation del panel |
Los frames de control también son válidos:
| Frame | Significado |
|---|---|
subscribed | Suscripción aceptada |
heartbeat | Frame keepalive |
dropped | El subscriber quedó atrasado y se descartaron eventos |
Cuando un cliente recibe dropped, debe resincronizarse con paneflow ps --json o paneflow status <target> --json.
wait
wait --idle usa el stream de eventos cuando está disponible y cae de forma segura cuando hace falta. wait --pattern sondea el scrollback reciente cada 500 ms y escanea las últimas 500 líneas.
| Modo | Ejemplo | Uso |
|---|---|---|
| Idle | paneflow wait --match reviewer --idle --timeout 600 | Continuar después de que el agente deje de trabajar |
| Pattern | paneflow wait --match backend --pattern '^DONE:' --timeout 300 | Continuar después de una línea centinela |
| Idle plus pattern | paneflow wait --match reviewer --idle --pattern '^REPORT_DONE' --timeout 600 | Exigir panel estable y marcador |
| Any o all | paneflow wait --match 'cmdline:claude' --pattern 'tests passed' --all | Coordinar varios paneles en modo pattern |
Los timeouts salen con código 4.
Claves de configuración
| Clave | Valor por defecto | Significado |
|---|---|---|
ai_unrestricted | false | Permite a la automatización IA de confianza enviar cuando está activo |
ai_injection_fence | true | Envuelve salida de terminal de pares como texto no confiable |
agent_stall_threshold_secs | defecto de app | Marca como stalled los turnos silenciosos en curso |
Códigos de salida
| Código | Significado |
|---|---|
0 | Éxito |
1 | Fallo de runtime |
2 | Error de uso de CLI |
3 | Objetivo no encontrado o ambiguo |
4 | Timeout de wait |