How joshuaisaact/petri-flow works
PetriFlow has two product tracks: declarative policies compiled into Petri-net tool gates for agent frameworks, and a general workflow runtime with analysis, persistence, CLI, and an interactive viewer/editor. The safety path runs from policy compilation through composed gate decisions and framework adapters. The workflow path defines nets, analyzes and executes them, then exposes them through CLI and viewer tooling. Relationships below rely on README capability statements and SOURCE INDEX references; unsampled implementation details are not asserted.
Main entry points: manager.ts Gate manager · App.tsx Viewer and editor · scheduler.ts Scheduler · engine.ts Firing engine
Components 28
Safety policies
- Rules compiler
packages/rules/src/compiler.ts
Tool gating
- Gate manager
packages/gate/src/manager.ts - Net composition
packages/gate/src/compose.ts - Deferred advance
packages/gate/src/advance.ts - Tool events
packages/gate/src/events.ts
Agent adapters
- Vercel AI adapter
packages/vercel-ai/src/index.ts - Pi adapter
packages/pi-extension/src/index.ts - Agent SDK adapter
packages/agent-sdk/src/index.ts - Claude Code hook
packages/claude-code/src/hook.ts - OpenClaw adapter
packages/openclaw/src/index.ts - Reusable skill nets
packages/pi-assistant/src/nets/research.ts
Workflow runtime
- Workflow definitions
workflows - Firing engine
packages/engine/src/engine.ts - Workflow analysis
packages/engine/src/analyse.ts - Workflow executor
packages/engine/src/executor.ts - Scheduler
packages/engine/src/scheduler.ts - Persistence adapters
packages/engine/src/persistence/sqlite-adapter.ts - Analysis CLI
packages/cli/src/cli.ts - Agent benchmark
workflows/agent-benchmark/definition.ts - Safety scenarios
comparisons/openclaw-safety/src/scenarios/sandbox-isolation.ts
Workflow viewer
- Viewer and editor
apps/viewer/src/App.tsx - Simulation state
apps/viewer/src/hooks/usePetriNet.ts - Live analysis
apps/viewer/src/hooks/useAnalysis.ts - Net canvas
apps/viewer/src/components/canvas/PetriNetCanvas.tsx - Editor state
apps/viewer/src/editor/useEditorState.ts - Graph layout
apps/viewer/src/layout/dagre.ts - Definition API
apps/viewer/src/editor/useDefinitionsApi.ts
Other components
- Agent tools
Connections 25
- Agent tools → Vercel AI adapter: calls tools
- Rules compiler → Gate manager: compiles policies
- Vercel AI adapter → Gate manager: wraps tools
- Pi adapter → Gate manager: intercepts calls
- Agent SDK adapter → Gate manager: uses callbacks
- Claude Code hook → Gate manager: gates hooks
- OpenClaw adapter → Gate manager: maps hooks
- Reusable skill nets → Gate manager: provides nets
- Gate manager → Net composition: dispatches calls
packages/gate/src/manager.ts - Gate manager → Deferred advance: advances state
packages/gate/src/manager.ts - Gate manager → Tool events: handles events
packages/gate/src/manager.ts - Workflow definitions → Firing engine: defines nets
- Firing engine → Workflow executor: fires transitions
- Workflow definitions → Workflow analysis: proves properties
- Scheduler → Workflow executor: ticks workflows
- Scheduler → Persistence adapters: persists state
- Analysis CLI → Workflow analysis: runs analysis
- Agent benchmark → Scheduler: runs workflow
- Safety scenarios → Firing engine: defines scenarios
- Viewer and editor → Simulation state: hosts simulation
- Viewer and editor → Live analysis: shows analysis
- Viewer and editor → Net canvas: renders net
- Viewer and editor → Editor state: hosts editing
- Editor state → Graph layout: requests layout
apps/viewer/src/editor/useEditorState.ts - Viewer and editor → Definition API: loads definitions