polyflow

에이전트는 이미 중단된 실행을 재개할 수 있습니다. 그러나 재개된 실행이 무엇을 할 수 있는지는 말해주지 못합니다.

polyflow는 AI 에이전트를 위한 워크플로우 엔진입니다. 에이전트는 다음 도구 호출 대신 워크플로우를 추론합니다. polyflow는 해당 워크플로우가 모델 검사를 통과할 때만 승인하고, 그런 다음 지속적으로 실행하여 에이전트에게 한 번에 하나의 작업 지시를 전달합니다.

MCP 서버로 제공되므로 MCP를 지원하는 모든 에이전트(OpenWorker, Claude Code, Cursor)는 해당 에이전트의 코어를 변경하지 않고 사용할 수 있습니다.

실험적이며, 검증되지 않았고, 동료 검토를 거치지 않았습니다. 이 검사는 증명이 아니라 일관성 검사이며, "완전(exhaustive)"은 항상 계약이 선언한 유한 도메인에 대한 완전함을 의미합니다. 모든 발견은 결과가 아니라 단서입니다.

루프

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

에이전트는 다음에 무엇이 올지 결정하지 않습니다. 하나의 지시를 어떻게 이행할지 추론하고(이것이 실제로 모델이 잘하는 일입니다) 결과를 보고합니다. 순서 지정, 재시도, 타이머, 중복 억제 및 종료 조건은 기계의 몫입니다.

Related MCP server: nano-vm-mcp

왜 이 방식인가: 상시 권한이 아닌 이유

오늘날 무인 자동화는 동사로 승인됩니다: "slack_send를 #cs에 허용" — 모델이 무엇을 하기로 결정하든 영원히. 계획이 매 실행마다 다시 계획되는 산문 형식의 지시 문자열일 때 이것이 한계입니다.

polyflow는 계획을 승인합니다. workflows/customer-brief/effect-invariants.mjs에는 사용자가 실제로 동의할 수 있는 문장이 들어 있습니다:

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

시작 시 계약이 선언한 도메인에 대해 도달 가능한 모든 방출 경로를 열거하고 검사합니다. 실패한 워크플로우는 등록되지 않습니다 — 플래그만 표시되는 것이 아니라 실행 불가능합니다:

[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는 의도적으로 손상된 쌍둥이입니다: 인간이 답하기 전에 검토에 들어가는 즉시 게시합니다. 여전히 ask_user를 호출하고, 같은 채널을 대상으로 하며, 상시 권한을 충족합니다. diff를 읽는 검토자는 쉽게 놓칠 수 있습니다. 게이트는 놓치지 않습니다.

빠른 시작

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

OpenWorker와 함께 실행

전제 조건: Node 22+ (polyflow는 node:sqlite를 사용합니다) 및 OpenWorker 설치. polyflow는 자체 API 키가 필요 없습니다 — 모델을 호출하지 않기 때문입니다.

1. 등록합니다. polyflow 디렉터리에서:

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

이렇게 하면 polyflow 항목이 OpenWorker의 전역 mcpServers 파일에 병합됩니다 — Connectors 페이지가 편집하는 것과 동일한 파일입니다 (Windows에서는 %APPDATA%\coworker\mcp.json, 그 외에는 ~/.config/coworker/mcp.json, $COWORKER_STATE_DIR이 둘 다를 재정의합니다). 교체가 아닌 병합 방식이며, 파싱할 수 없는 파일은 건드리지 않습니다.

2. OpenWorker를 다시 시작합니다. 시작하거나 감독할 polyflow 데몬은 없습니다: OpenWorker는 세션이 열릴 때 stdio를 통해 bin/polyflow-mcp.mjs를 생성하고 세션과 함께 종료합니다. 실행 상태는 POLYFLOW_DB의 SQLite 파일에 저장되므로 둘 다에서도 유지됩니다.

3. 정상 기동을 확인합니다. 여섯 개의 도구가 mcp__polyflow__*로 나타납니다. 에이전트에게 *"실행할 수 있는 워크플로우를 나열해 줘"*라고 요청하세요 — customer-brief, 해당 admitted: true, 그리고 승인된 다섯 가지 보장을 반환해야 합니다. 그렇지 않으면 Connectors 페이지에 상시 오류가 표시되고, 서버 자체의 시작 줄(admitted: / REFUSED:)은 stderr로 출력됩니다.

4. 사용합니다. 특별한 것은 없습니다: 워크플로우가 다루는 작업을 에이전트에게 주면 에이전트가 스스로 워크플로우를 선택합니다 — 이것이 FINDINGS-phase3.md가 측정하는 것입니다. 반복 작업을 적용하려면 작업을 설명하는 지시가 있는 일반 OpenWorker 자동화를 만드세요. 워크플로우는 매 실행마다 처음부터 시작하는 대신 파생 키로 다시 연결됩니다.

영역(Areas). --agent는 에이전트 클래스 영역(이 종류의 에이전트가 사용하는 워크플로우 라이브러리)이고 --workspace는 인스턴스 영역(이 실행들이 속한 영역)입니다. 하나의 polyflow 설치로 여러 워크스페이스를 제공할 수 있습니다 — 워크스페이스마다 다른 --workspace로 한 번씩 등록하고, 같은 POLYFLOW_DB를 가리켜 저장소를 공유하거나 다른 파일을 가리켜 분리할 수 있습니다.

자체 워크플로우 추가. workflows/customer-brief/를 복사하고 여섯 개의 파일을 편집하세요 (아래 워크플로우 참조). 서버를 다시 시작하세요: 방출 검사에 실패한 워크플로우는 시작 시 거부되며 전혀 시작할 수 없으므로, 잘못된 편집은 새벽 3시가 아니라 즉시 명확하게 실패합니다.

권한. 설치된 항목은 의도적으로 requires_approval: false로 설정됩니다 — polyflow 도구는 머신 외부에 접근하지 않으며, 실행의 실제 부작용은 에이전트 자신의 도구가 수행하고, 이 도구들은 자체 게이트를 유지합니다. 모든 workflow_report에서 프롬프트를 띄우면 에이전트와 자체 기록 사이에 대화 상자가 놓이게 됩니다. 항목은 또한 읽기 전용 도구에 대해 tool_risk를 선언하며, upstream/0001-mcp-per-tool-risk-level.patch가 적용되면 존중되고 없으면 무해하게 무시됩니다.

polyrun의 출처. polyflow는 polyrun을 프로세스에 내장하며, node_modules/polygraph에서 해석되고, 그다음 형제 체크아웃에서 해석됩니다. POLYFLOW_POLYRUN이 둘 다를 재정의합니다.

기타 에이전트 호스트

polyflow는 일반 MCP stdio 서버이므로 MCP를 말할 수 있는 모든 것이 사용할 수 있습니다. 설치 프로그램은 각 호스트에 맞는 파일을 작성합니다:

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

두 호스트는 다른 형태를 가지며 파일로 작성되지 않고 출력됩니다:

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는 ~/.kiro/settings/mcp.json(사용자) 또는 .kiro/settings/mcp.json(워크스페이스, 이름 충돌 시 우선)에서 mcpServers를 읽습니다. Kiro Crew의 반복 무인 작업은 OpenWorker의 예약 작업과 동일한 형태이며, FINDINGS-phase3.md의 결과가 다루는 사례입니다.

• NVIDIA NeMo Agent Toolkit은 mcp_client 함수 그룹을 통해 연결합니다 (nvidia-nat-mcp 필요). 출력된 블록은 그룹을 선언하고 워크플로우의 tool_names에 추가합니다. NeMo는 자체적으로 MCP 서버로도 실행될 수 있으므로, NeMo 워크플로우는 polyflow 작업 지시가 명명하는 도구 중 하나가 될 수 있습니다.

• AWS Agent Registry는 런타임이 아닌 카탈로그입니다: 레코드를 게시하면 조직의 다른 사람과 에이전트가 polyflow를 발견할 수 있습니다. 레코드는 HTTPS 엔드포인트에서 동기화할 수 있는데, stdio 서버는 이를 제공할 방법이 없으므로 출력된 명령은 대신 수동 MCP 레코드를 생성합니다.

OpenWorker 경로만 종단 간 테스트되었습니다 (FINDINGS-phase2.md 참조). 나머지는 각 호스트의 문서화된 구성 형식으로 작성되었으며 실행되지 않았습니다.

어떤 호스트를 사용하든 환경 변수:

도구

영역

두 계층이며 OpenWorker에 새 필드가 필요 없습니다:

• 에이전트 영역 — 에이전트 클래스당 하나 (openworker/cowork). 워크플로우 라이브러리를 소유합니다: 이 종류의 에이전트가 할 수 있는 일. ScheduledTask.agent에 매핑됩니다.

• 인스턴스 영역 — 실행 중인 복사본당 하나 (workspace). 활성 실행과 해당 저널을 소유합니다. 이미 coworker.memory.Scope.WORKSPACE인 workspace에 매핑됩니다.

인스턴스 ID는 agent | instance | workflow | key에서 파생되므로 시작과 연결이 하나의 호출입니다.

워크플로우

디렉터리에 있는 여섯 개의 파일:

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

에이전트에서 작동하게 만드는 역전: polyrun에서 런타임이 효과를 실행합니다. polyflow에는 자격 증명, 커넥터, 권한 엔진이 없습니다 — 에이전트가 세 가지 모두를 가지고 있습니다. 따라서 효과는 되돌려 주는 작업 지시입니다. 핸들러는 대기하고, 에이전트가 지시를 수령하여 자체 게이트 아래에서 도구를 실행하고 보고합니다. 그런 다음에만 완료 작업이 디스패치됩니다.

내구성은 임대(lease) 메커니즘에서 나옵니다. 보류 맵은 인메모리이므로 충돌 시 약속이 손실되고, 임대가 만료되며, 효과가 다시 수령되고 지시가 다시 제공됩니다 — 동일한 의도 ID, 최소 한 번(at-least-once), 기계가 흡수합니다.

테스트가 증명하는 것

✔ 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

재시작 테스트가 중요한 테스트입니다: 세션 1은 실행을 승인 단계까지 진행하고 종료됩니다. 세션 2는 대화, 기록, 재생이 없는 다른 프로세스입니다 — 상태가 애초에 메시지에 없었기 때문입니다. 실행을 정확히 중단된 지점에서 재개하며, 두 세션에 걸쳐 정확히 한 번의 게시가 발생합니다.

아직 구축되지 않은 것

• 승격(Promotion). 여기서 워크플로우는 수작업으로 작성됩니다. 계획은 저널에서 반복적인 실행 형태를 마이닝하여 검토용 머신을 제안하는 것입니다 — 예측이 아닌 역사로부터의 귀납. 작업별 머신 작성은 재사용되지 않으면 대체하는 도구 호출보다 비용이 더 듭니다.

• 버전 관리. polyvers는 변경된 워크플로우를 진행 중인 실행에 대해 게이트합니다. 아직 연결되지 않았습니다.

• 감사. 저널은 이미 트레이스 코퍼스입니다. 이에 대한 polyrun audit는 아직 연결되지 않았습니다.

• 코어 변경이 필요한 OpenWorker 접합부: 대기 중인 지시를 Inbox로 라우팅하는 것과 ScheduledTask의 workflow_ref. FINDINGS-phase0.md를 참조하세요.