polyflow

Un agente ya puede reanudar una ejecución en pausa. No puede decirte qué se le permite hacer a la ejecución reanudada.

polyflow es un motor de flujos de trabajo para agentes de IA. El agente razona un flujo de trabajo en lugar de la siguiente llamada a una herramienta; polyflow admite ese flujo de trabajo solo si lo verifica mediante modelo, luego lo ejecuta de manera durable y entrega al agente una orden de trabajo a la vez.

Se distribuye como un servidor MCP, por lo que cualquier agente compatible con MCP — OpenWorker, Claude Code, Cursor — puede usarlo sin cambios en el núcleo de ese agente.

Experimental, no probado, no revisado por pares. La verificación es una comprobación de consistencia, no una prueba, y "exhaustivo" siempre significa exhaustivo sobre el dominio finito que declara el contrato. Cada hallazgo es una pista, no un resultado.

El bucle

tools → observe → reason → WORKFLOW ──▶ polyflow admits it (or refuses)
                                            │
                        ┌───────────────────┘
                        ▼
        one work order  →  the agent runs the tool, through its own
                           permission gates, with its own credentials
                        →  workflow_report
                        →  next work order … until terminal

El agente nunca decide qué viene después. Razona sobre cómo cumplir una orden — que es algo en lo que un modelo realmente es bueno — e informa el resultado. La secuenciación, los reintentos, los temporizadores, la supresión de duplicados y las condiciones terminales pertenecen a la máquina.

Related MCP server: nano-vm-mcp

Por qué esto y no una concesión permanente

Hoy una automatización no supervisada se aprueba por verbo: "permitir slack_send a #cs", para siempre, para lo que sea que el modelo decida hacer con eso. Ese es el techo cuando el plan es una cadena de instrucciones en prosa que se replanifica en cada ejecución.

polyflow aprueba un plan. workflows/customer-brief/effect-invariants.mjs contiene las frases a las que un usuario realmente puede acceder:

{ name: 'no-post-without-prior-approval',
  pred: (path) => path.emitted.every((e, i) =>
    e.kind !== 'post_brief' || path.actionBefore('APPROVED', i)) }

El arranque enumera cada camino de emisión alcanzable sobre el dominio declarado del contrato y los comprueba. Un flujo de trabajo que falla no se registra — no se marca, no es ejecutable:

[polyflow] admitted: customer-brief — paths explored: 5 · states seen: 10 · exhaustive within declared domains
[polyflow] REFUSED: unsafe-brief
[polyflow]   no-post-without-prior-approval

test/fixtures/unsafe-brief es el gemelo deliberadamente roto: publica al entrar en revisión, antes de que el humano responda. Todavía llama a ask_user, todavía apunta al mismo canal, todavía satisface el permiso permanente. Un revisor que lea el diff podría fácilmente pasarlo por alto. La compuerta no.

Inicio rápido

npm install                    # pulls polygraph (polyrun) as a dependency
npm test                       # 14 tests, no API key, deterministic
node bin/polyflow-mcp.mjs      # MCP stdio server

Ejecución junto a OpenWorker

Requisitos previos: Node 22+ (polyflow usa node:sqlite), y OpenWorker instalado. polyflow no necesita su propia clave API — nunca llama a un modelo.

1. Regístralo. Desde el directorio de polyflow:

node bin/polyflow-install.mjs --agent openworker/cowork --workspace acme
# --print shows the entry and the target path without writing anything

Esto fusiona una entrada polyflow en el archivo mcpServers global de OpenWorker — el mismo que edita la página de Conectores (%APPDATA%\coworker\mcp.json en Windows, ~/.config/coworker/mcp.json en otros casos, $COWORKER_STATE_DIR anula ambos). Fusiona en lugar de reemplazar, y se niega a tocar un archivo que no puede analizar.

2. Reinicia OpenWorker. No hay un demonio de polyflow que iniciar o supervisar: OpenWorker lanza bin/polyflow-mcp.mjs sobre stdio cuando se abre una sesión y lo derriba con la sesión. El estado de ejecución vive en el archivo SQLite en POLYFLOW_DB, por lo que sobrevive a ambos.

3. Comprueba que se haya levantado. Las seis herramientas aparecen como mcp__polyflow__*. Pídele al agente que "liste los flujos de trabajo que puedes ejecutar" — debería devolver customer-brief, su admitted: true, y las cinco garantías bajo las que fue admitido. Si no lo hace, la página de Conectores muestra el error permanente, y las líneas de arranque del servidor (admitted: / REFUSED:) van a stderr.

4. Úsalo. Nada especial: dale al agente una tarea que cubra un flujo de trabajo y él recoge el flujo de trabajo por sí solo — eso es lo que mide FINDINGS-phase3.md. Para poner un trabajo recurrente en él, crea una automatización normal de OpenWorker cuyas instrucciones describan la tarea; el flujo de trabajo se re-adjunta por clave derivada en cada disparo en lugar de empezar de nuevo.

Áreas. --agent es el área de clase de agente (de qué biblioteca de flujos de trabajo se sirve este tipo de agente) y --workspace es el área de instancia (de quién son estas ejecuciones). Una instalación de polyflow puede servir varios workspaces — regístralo una vez por workspace con un --workspace diferente, apuntando al mismo POLYFLOW_DB para compartir un almacén o a archivos diferentes para mantenerlos separados.

Agregar tu propio flujo de trabajo. Copia workflows/customer-brief/ y edita los seis archivos (ver Un flujo de trabajo más abajo). Reinicia el servidor: un flujo de trabajo que falla su verificación de emisión se rechaza en el arranque y no se puede iniciar en absoluto, por lo que una edición mala falla ruidosamente en lugar de a las 3AM.

Permisos. La entrada instalada establece requires_approval: false deliberadamente — las herramientas de polyflow no alcanzan nada fuera de la máquina, y los efectos secundarios reales de la ejecución son las herramientas PROPIAS del agente, que mantienen sus propias compuertas. Preguntar en cada workflow_report pondría un diálogo entre el agente y su propio registro. La entrada también declara tool_risk para las herramientas de solo lectura, respetado con upstream/0001-mcp-per-tool-risk-level.patch aplicado e ignorado sin problemas sin él.

De dónde viene polyrun. polyflow incrusta polyrun en proceso, resuelto desde node_modules/polygraph, luego una copia de trabajo hermana; POLYFLOW_POLYRUN anula ambos.

Otros hosts de agentes

polyflow es un servidor MCP stdio simple, por lo que cualquier cosa que hable MCP puede usarlo. El instalador escribe el archivo correcto para cada host:

node bin/polyflow-install.mjs --host kiro          # ~/.kiro/settings/mcp.json
node bin/polyflow-install.mjs --host kiro --scope workspace   # ./.kiro/settings/mcp.json
node bin/polyflow-install.mjs --host claude-code   # ./.mcp.json
node bin/polyflow-install.mjs --host generic       # prints the entry, writes nothing

Dos hosts toman una forma diferente y se imprimen en lugar de escribirse:

node bin/polyflow-install.mjs --host nemo      # YAML for a NeMo Agent Toolkit workflow
node bin/polyflow-install.mjs --host registry  # AWS CLI call to publish an Agent Registry record

• Kiro / Kiro Crew lee mcpServers desde ~/.kiro/settings/mcp.json (usuario) o .kiro/settings/mcp.json (workspace, que gana en conflicto de nombres). Los trabajos recurrentes no supervisados de Kiro Crew tienen la misma forma que los trabajos programados de OpenWorker, que es el caso al que se refieren los resultados en FINDINGS-phase3.md.

• NVIDIA NeMo Agent Toolkit se conecta a través de su grupo de funciones mcp_client (necesita nvidia-nat-mcp). El bloque impreso declara el grupo y lo agrega a tool_names de un flujo de trabajo. NeMo también puede ejecutarse como un servidor MCP en sí mismo, por lo que un flujo de trabajo de NeMo puede ser una de las herramientas que una orden de trabajo de polyflow nombre.

• AWS Agent Registry es un catálogo más que un runtime: publicar un registro permite que otras personas y agentes de la organización descubran polyflow. Los registros se pueden sincronizar desde un endpoint HTTPS, que un servidor stdio no tiene forma de ofrecer, por lo que el comando impreso crea un registro MCP manual en su lugar.

Solo la ruta de OpenWorker se ha ejercitado de extremo a extremo (ver FINDINGS-phase2.md). Los demás están construidos a partir del formato de configuración documentado de cada host y no se han ejecutado.

Variables de entorno, independientemente del host que uses:

Herramientas

Áreas

Dos niveles, y no necesitan nuevos campos en OpenWorker:

• área de agente — una por clase de agente (openworker/cowork). Posee la biblioteca de flujos de trabajo: lo que este tipo de agente sabe hacer. Se asigna a ScheduledTask.agent.

• área de instancia — una por copia en ejecución (workspace). Posee las ejecuciones activas y sus diarios. Se asigna a workspace, que ya es coworker.memory.Scope.WORKSPACE.

El identificador de instancia se deriva de agent | instance | workflow | key, por eso iniciar y adjuntar son una sola llamada.

Un flujo de trabajo

Seis archivos en un directorio:

polyflow.workflow.json   name, area, tools{effect kind -> agent tool},
                         key{template,fields} — the run's identity, derived
contract.json            states, actions, finite data domain
machine.cjs              SAM v2 strict-profile module
effects.cjs              pure mapper: transition -> work orders
effects.manifest.json    completion actions + retry policy per kind
effect-invariants.mjs    what may be EMITTED, on every reachable path

La inversión que hace que esto funcione para agentes: en polyrun el runtime ejecuta efectos. polyflow no tiene credenciales, ni conectores, ni motor de permisos — el agente tiene los tres. Así que un efecto es una orden de trabajo devuelta. El handler se detiene; el agente reclama la orden, ejecuta la herramienta bajo sus propias compuertas y reporta. Solo entonces se ejecuta la acción de finalización.

La durabilidad surge de la maquinaria de arrendamiento. El mapa pendiente está en memoria, por lo que un bloqueo pierde la promesa, el arrendamiento expira, el efecto se reclama de nuevo y la orden se vuelve a ofrecer — mismo id de intención, al menos una vez, absorbido por la máquina.

Lo que demuestran las pruebas

✔ the admission gate certifies the demo workflow exhaustively
✔ workflow_list reports the guarantees the run was admitted under
✔ happy path: one order at a time, ending posted
✔ the run key is derived from input, not chosen by the caller
✔ an invalid key field is refused with an instruction, not honoured
✔ a finished run says so, and says not to start another
✔ start is idempotent: re-attaching returns the run in progress
✔ a denial is a result, not a fault — and no post is ever ordered
✔ zero tickets ends the run rather than posting an empty brief
✔ a duplicate report is refused, not double-executed
✔ an out-of-band action that does not apply is an observable reject
✔ a workflow that can post before approval is REFUSED and cannot be started
✔ a run outlives the process: restart re-offers the open work order
✔ initialize, tools/list, tools/call over stdio

La prueba de reinicio es la que importa: la sesión 1 lleva la ejecución al paso de aprobación y muere; la sesión 2 es un proceso diferente sin conversación, sin transcripción y sin reproducción — porque el estado nunca estuvo en los mensajes para empezar. Retoma la ejecución exactamente donde estaba, y exactamente una publicación ocurre en ambas.

No construido aún

• Promoción. Los flujos de trabajo se escriben a mano aquí. El plan es extraer formas de ejecución recurrentes de los diarios y proponer una máquina para revisión — inducción desde la historia, no previsión. Crear una máquina por tarea cuesta más que las llamadas a herramientas que reemplaza, a menos que se reutilice.

• Versionado. polyvers controla un flujo de trabajo cambiado contra ejecuciones en vuelo; no está conectado.

• Auditoría. El diario ya es un corpus de trazas; polyrun audit contra él no está conectado.

• Las costuras de OpenWorker que necesitan cambios en el núcleo: enrutar una orden detenida al Bandeja de entrada, y workflow_ref en ScheduledTask. Ver FINDINGS-phase0.md.