polyflow

Ein Agent kann einen geparkten Lauf bereits wieder aufnehmen. Er kann dir nicht sagen, was der wiederaufgenommene Lauf tun darf.

polyflow ist eine Workflow-Engine für KI-Agenten. Der Agent denkt über einen Workflow nach, nicht über den nächsten Tool-Aufruf; polyflow lässt diesen Workflow nur zu, wenn er eine Modellprüfung besteht, führt ihn dann dauerhaft aus und reicht dem Agenten jeweils einen Arbeitsauftrag nach dem anderen.

Es wird als MCP-Server ausgeliefert, sodass jeder MCP-fähige Agent — OpenWorker, Claude Code, Cursor — ihn ohne Änderungen am Kern des Agenten nutzen kann.

Experimentell, unbewiesen, nicht peer-reviewed. Die Prüfung ist eine Konsistenzprüfung, kein Beweis, und „vollständig“ bedeutet immer vollständig über die endliche Domäne, die der Vertrag deklariert. Jeder Befund ist eine Spur, kein Ergebnis.

Die Schleife

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

Der Agent entscheidet nie, was als Nächstes kommt. Er denkt darüber nach, wie er einen Auftrag erfüllt — was ein Modell tatsächlich gut kann — und meldet das Ergebnis. Sequenzierung, Wiederholungen, Timer, Duplikatunterdrückung und Endbedingungen gehören zur Maschine.

Related MCP server: nano-vm-mcp

Warum das und nicht eine pauschale Genehmigung

Heute wird eine unbeaufsichtigte Automatisierung per Verb genehmigt: „slack_send an #cs erlauben“, für immer, für das, was das Modell damit zu tun beschließt. Das ist die Obergrenze, wenn der Plan eine Prosa-Anweisungszeichenfolge ist, die bei jedem Lauf neu geplant wird.

polyflow genehmigt einen Plan. workflows/customer-brief/effect-invariants.mjs enthält die Sätze, denen ein Nutzer tatsächlich zustimmen kann:

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

Beim Start wird jeder erreichbare Emissionspfad über die deklarierte Domäne des Vertrags aufgezählt und geprüft. Ein Workflow, der fehlschlägt, wird nicht registriert — nicht markiert, nicht ausführbar:

[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 ist der absichtlich defekte Zwilling: Er postet beim Eintritt in die Überprüfung, bevor der Mensch antwortet. Er ruft immer noch ask_user auf, zielt immer noch auf denselben Kanal, erfüllt immer noch die pauschale Genehmigung. Ein Prüfer, der das Diff liest, könnte es leicht übersehen. Das Tor nicht.

Schnellstart

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

Neben OpenWorker ausführen

Voraussetzungen: Node 22+ (polyflow verwendet node:sqlite) und OpenWorker installiert. polyflow benötigt keinen eigenen API-Schlüssel — es ruft nie ein Modell auf.

1. Registrieren. Aus dem polyflow-Verzeichnis:

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

Dies fügt einen polyflow-Eintrag in OpenWorkers globale mcpServers-Datei ein — dieselbe, die die Connectors-Seite bearbeitet (%APPDATA%\coworker\mcp.json unter Windows, ~/.config/coworker/mcp.json sonst, $COWORKER_STATE_DIR überschreibt beide). Es fügt zusammen, statt zu ersetzen, und weigert sich, eine Datei zu berühren, die es nicht parsen kann.

2. OpenWorker neu starten. Es gibt keinen polyflow-Daemon, der gestartet oder überwacht werden muss: OpenWorker startet bin/polyflow-mcp.mjs über stdio, wenn eine Sitzung geöffnet wird, und beendet es mit der Sitzung. Der Laufzustand liegt in der SQLite-Datei unter POLYFLOW_DB, sodass er beides überlebt.

3. Prüfen, ob es hochgekommen ist. Die sechs Tools erscheinen als mcp__polyflow__*. Bitte den Agenten, „die Workflows aufzulisten, die du ausführen kannst“ — er sollte mit customer-brief, dessen admitted: true und den fünf Garantien zurückkommen, unter denen er zugelassen wurde. Wenn nicht, zeigt die Connectors-Seite den anstehenden Fehler, und die eigenen Startzeilen des Servers (admitted: / REFUSED:) gehen an stderr.

4. Nutzen. Nichts Besonderes: Gib dem Agenten eine Aufgabe, die ein Workflow abdeckt, und er nimmt den Workflow von selbst auf — das misst FINDINGS-phase3.md. Um einen wiederkehrenden Auftrag darauf zu legen, erstelle eine gewöhnliche OpenWorker-Automatisierung, deren Anweisungen die Aufgabe beschreiben; der Workflow hängt sich bei jedem Auslösen über den abgeleiteten Schlüssel wieder an, statt neu zu beginnen.

Bereiche. --agent ist der Agent-Klassen-Bereich (welche Workflow-Bibliothek diese Art von Agent nutzt) und --workspace ist der Instanz-Bereich (wessen Läufe das sind). Eine polyflow-Installation kann mehrere Workspaces bedienen — registriere sie einmal pro Workspace mit einem anderen --workspace, zeige auf dieselbe POLYFLOW_DB, um einen Speicher zu teilen, oder auf verschiedene Dateien, um sie getrennt zu halten.

Eigenen Workflow hinzufügen. Kopiere workflows/customer-brief/ und bearbeite die sechs Dateien (siehe Ein Workflow unten). Starte den Server neu: Ein Workflow, der seine Emissionsprüfung nicht besteht, wird beim Start abgelehnt und kann überhaupt nicht gestartet werden, sodass eine schlechte Bearbeitung laut scheitert, statt um 3 Uhr morgens.

Berechtigungen. Der installierte Eintrag setzt requires_approval: false bewusst — polyflow-Tools erreichen nichts außerhalb der Maschine, und die echten Nebenwirkungen des Laufs sind die EIGENEN Tools des Agenten, die ihre eigenen Tore behalten. Bei jedem workflow_report nachzufragen würde einen Dialog zwischen den Agenten und seine eigene Buchhaltung stellen. Der Eintrag deklariert auch tool_risk für die schreibgeschützten Tools, das mit upstream/0001-mcp-per-tool-risk-level.patch angewendet wird und ohne es harmlos ignoriert wird.

Woher polyrun kommt. polyflow bettet polyrun prozessintern ein, aufgelöst aus node_modules/polygraph, dann aus einem Geschwister-Checkout; POLYFLOW_POLYRUN überschreibt beides.

Andere Agent-Hosts

polyflow ist ein einfacher MCP-stdio-Server, also kann alles, was MCP spricht, ihn nutzen. Der Installer schreibt die richtige Datei für jeden 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

Zwei Hosts haben eine andere Form und werden gedruckt statt geschrieben:

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 liest mcpServers aus ~/.kiro/settings/mcp.json (Benutzer) oder .kiro/settings/mcp.json (Workspace, der bei Namenskonflikt gewinnt). Kiro Crews wiederkehrende unbeaufsichtigte Aufträge haben dieselbe Form wie OpenWorkers geplante Aufträge, was der Fall ist, um den es in den Ergebnissen in FINDINGS-phase3.md geht.

• NVIDIA NeMo Agent Toolkit verbindet sich über seine mcp_client-Funktionsgruppe (benötigt nvidia-nat-mcp). Der gedruckte Block deklariert die Gruppe und fügt sie zu den tool_names eines Workflows hinzu. NeMo kann auch selbst als MCP-Server laufen, sodass ein NeMo-Workflow eines der Tools sein kann, die ein polyflow-Arbeitsauftrag nennt.

• AWS Agent Registry ist eher ein Katalog als eine Laufzeit: Das Veröffentlichen eines Datensatzes ermöglicht anderen Personen und Agenten in der Organisation, polyflow zu entdecken. Datensätze können von einem HTTPS-Endpunkt synchronisiert werden, was ein stdio-Server nicht anbieten kann, daher erstellt der gedruckte Befehl einen manuellen MCP-Datensatz.

Nur der OpenWorker-Pfad wurde Ende-zu-Ende getestet (siehe FINDINGS-phase2.md). Die anderen sind aus dem dokumentierten Konfigurationsformat jedes Hosts aufgebaut und wurden nicht ausgeführt.

Env-Variablen, egal welchen Host du verwendest:

Tools

Bereiche

Zwei Ebenen, und sie benötigen keine neuen Felder in OpenWorker:

• Agent-Bereich — einer pro Agent-Klasse (openworker/cowork). Besitzt die Workflow-Bibliothek: was diese Art von Agent tun kann. Mappt auf ScheduledTask.agent.

• Instanz-Bereich — einer pro laufender Kopie (workspace). Besitzt die Live-Läufe und ihre Journale. Mappt auf workspace, das bereits coworker.memory.Scope.WORKSPACE ist.

Die Instanz-ID wird aus agent | instance | workflow | key abgeleitet, weshalb Start und Anhängen ein einziger Aufruf sind.

Ein Workflow

Sechs Dateien in einem Verzeichnis:

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

Die Umkehrung, die das für Agenten funktionieren lässt: In polyrun führt die Laufzeit Effekte aus. polyflow hat keine Anmeldeinformationen, keine Konnektoren und keine Berechtigungs-Engine — der Agent hat alle drei. Ein Effekt ist also ein zurückgereichter Arbeitsauftrag. Der Handler parkt; der Agent beansprucht den Auftrag, führt das Tool unter seinen eigenen Toren aus und meldet. Erst dann wird die Abschlussaktion ausgelöst.

Haltbarkeit ergibt sich aus der Lease-Mechanik. Die ausstehende Map ist im Speicher, sodass ein Absturz das Versprechen verliert, die Lease abläuft, der Effekt erneut beansprucht und der Auftrag erneut angeboten wird — gleiche Intent-ID, mindestens einmal, von der Maschine absorbiert.

Was die Tests beweisen

✔ 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

Der Neustart-Test ist der, der zählt: Sitzung 1 treibt den Lauf bis zum Genehmigungsschritt und stirbt; Sitzung 2 ist ein anderer Prozess ohne Konversation, ohne Transkript und ohne Wiedergabe — weil der Zustand nie in den Nachrichten war. Sie nimmt den Lauf genau dort wieder auf, wo er war, und genau ein Post passiert über beide.

Noch nicht gebaut

• Promotion. Workflows werden hier von Hand erstellt. Der Plan ist, wiederkehrende Laufformen aus Journalen zu minen und eine Maschine zur Überprüfung vorzuschlagen — Induktion aus der Geschichte, nicht Voraussicht. Eine Maschine pro Aufgabe zu erstellen kostet mehr als die Tool-Aufrufe, die sie ersetzt, es sei denn, sie wird wiederverwendet.

• Versionierung. polyvers sperrt einen geänderten Workflow gegen laufende Läufe; nicht verdrahtet.

• Audit. Das Journal ist bereits ein Trace-Korpus; polyrun audit dagegen ist nicht verdrahtet.

• Die OpenWorker-Nähte, die Kernänderungen benötigen: das Weiterleiten eines geparkten Auftrags an den Posteingang und workflow_ref auf ScheduledTask. Siehe FINDINGS-phase0.md.