🇫🇷 Version française
See also: ProcessTypes comparison guide · YAML schema · Back to index
Finite state machine (FSM) engine
Overview
Orkeon provides a generic finite state machine framework (StateMachine<TState, TEvent>) in the Domain layer, with a built-in circuit breaker (CircuitBreakerPolicy) that stops a runaway loop. It is a building block for your own code and for three shipped consumers:
orkeon forgeruns its session cycle (brief → blueprint → render → validate → test → diagnose → verdict) on aStateMachine<ForgeState, ForgeTrigger>(ForgeStateMachineFactory).- The Graph mode bounds its
StateGraphruns with aCircuitBreakerPolicybuilt from the crew'sgraph:block. - The corrective RAG graph (
CorrectiveRagPipeline) bounds its retrieve → evaluate → regenerate loop with its ownCircuitBreakerPolicy.
No task state machine. A crew's tasks do not run through an FSM. What bounds a task is its agent loop: the agent's
maxIter, a stop after 3 consecutive identical tool errors, and the output-validation retries (an agent with two iterations left is told once; one that reachesmaxItergets a last tool-free turn, and its task is flaggedendedOnIterationCap; this is the main agent loop, the native tool-calling and legacy text fallback loops do neither and still end on the cap). A YAMLcircuitBreaker:block, at the crew root or on a task, is refused at load. In YAML, the only circuit-breaker setting is a Graph crew'sgraph:block (see YAML schema).
Architecture
The framework components live in Orkeon.Domain.Common.StateMachine:
| Class | Role |
|---|---|
StateMachine<TState, TEvent> |
Thread-safe FSM engine (lock) with built-in circuit breaker |
StateMachineBuilder<TState, TEvent> |
Fluent API to declare the state graph |
CircuitBreakerPolicy |
Protection threshold configuration, presets Strict / Default / Permissive |
CircuitBreakerStatus |
Snapshot of the breaker (same file as the policy) |
TransitionResult<TState, TEvent> |
Result of a transition (states, trigger, ordinal, timestamp) |
IStateMachine<TState, TEvent> |
Read-only interface for observation |
IMutableStateMachine<TState, TEvent> |
Interface with Fire(), TryFire(), ResetCircuitBreaker(), events |
CircuitBrokenException, InvalidTransitionException<TState, TEvent> |
Tripped breaker; no transition for this state + event |
CircuitBreakerPolicyFactory (Orkeon.Infrastructure.Configuration) turns a Graph crew's graph: block into a policy (ResolveGraph).
Circuit breaker
The circuit breaker is built directly into StateMachine<TState, TEvent> and checks four conditions before each transition:
Protection mechanisms
| Mechanism | Parameter | Description |
|---|---|---|
| Max transitions | MaxTransitions |
Total number of allowed transitions |
| Per-state timeout | StateTimeout |
Maximum time since the last transition (TimeSpan.Zero disables it) |
| Cycle detection | MaxStateVisits |
Maximum number of visits to the same state (0 disables it) |
| Total duration | MaxTotalDuration |
Maximum lifetime since the first transition (TimeSpan.Zero disables it) |
When a condition is violated, two behaviors are possible depending on UseDegradedMode:
false: aCircuitBrokenExceptionis thrown with a detailedCircuitBreakerStatustrue: the machine transitions to the degraded state declared withWithDegradedState(...); without a declared degraded state it throws as above
TryFire() returns false instead of throwing, for a tripped breaker as for a missing transition. A guard that rejects every candidate transition surfaces as an InvalidTransitionException. ResetCircuitBreaker() clears the trip and the counters.
Presets
Three presets are provided via CircuitBreakerPolicy:
| Preset | MaxTransitions | StateTimeout | MaxStateVisits | MaxTotalDuration | DegradedMode |
|---|---|---|---|---|---|
Strict |
50 | 2 min | 5 | 10 min | true |
Default |
100 | 5 min | 10 | 30 min | false |
Permissive |
1000 | 30 min | 50 | 2 h | false |
new CircuitBreakerPolicy() equals Default. Strict is the fallback of StateGraph and of CircuitBreakerPolicyFactory.ResolveGraph when graph: names no preset (or an unknown one).
Observability
The machine exposes two events:
OnTransition: raised after each successful transition, with aTransitionResult(FromState,ToState,Trigger,TransitionOrdinal,Timestamp,StateChanged)OnCircuitBroken: raised when the circuit trips, with aCircuitBreakerStatusincluding a per-state visit histogram
CircuitBreakerStatus provides a complete snapshot: IsBroken, BrokenReason, TotalTransitions, TimeInCurrentState, CurrentStateVisitCount, TotalElapsed, StateVisitHistogram. The read-only interface also offers CurrentState, IsTerminal, TransitionCount, GetPermittedEvents() and CanFire(event).
Typed guards
A transition can carry a guard over a typed context — WithGuard<TContext>(predicate, description) — and an action. Fire(event, context) evaluates the guards of the candidate transitions in declaration order and takes the first that passes; when every guard rejects, the call raises an InvalidTransitionException (TryFire returns false).
Usage in C# code
Building a state machine
The framework lets you define any state graph:
var fsm = new StateMachineBuilder<MyState, MyEvent>()
.WithInitialState(MyState.Idle)
.WithTerminalStates(MyState.Done, MyState.Error)
.WithDegradedState(MyState.Error)
.WithCircuitBreaker(new CircuitBreakerPolicy
{
MaxTransitions = 50,
StateTimeout = TimeSpan.FromMinutes(2),
MaxStateVisits = 5,
UseDegradedMode = true
})
.When(MyState.Idle, MyEvent.Start)
.TransitionTo(MyState.Processing)
.WithGuard<MyContext>(ctx => ctx.IsReady, "Must be ready")
.WithAction((from, to) => Log($"{from} -> {to}"))
.Done()
.When(MyState.Processing, MyEvent.Complete)
.TransitionTo(MyState.Done)
.Done()
.Build();
AddTransition(from, trigger, to) is the shortcut for a transition without guard or action; WithStateKey / WithEventKey supply the key functions when TState / TEvent are not enums.
The scripting DSL has its own
stateMachine()literal (fsm.d.ts), a separate JavaScript implementation without the circuit breaker — see Scripting.
Relationship with the existing code
Lifecycle states
The lifecycle states of agents, tasks and crews (AgentStatus, TaskStatus, CrewStatus: Pending → InProgress → Completed…) are guarded by the aggregates themselves — a task that is not Pending refuses to start — and a run moves them as it goes (Events). They do not use this engine.
Process strategies
The IProcessStrategy implementations execute a task through IAgentExecutionService and its agent loop; none of them builds a state machine. The Graph mode is the one strategy that applies a CircuitBreakerPolicy, to its StateGraph runner.
Tests
| Test file | Coverage |
|---|---|
Orkeon.Domain.Tests/Common/StateMachine/StateMachineTests.cs |
Valid/invalid transitions, terminal states, complete cycle |
Orkeon.Domain.Tests/Common/StateMachine/StateMachineGuardTests.cs |
Typed guards, guard priority, on-transition actions |
Orkeon.Domain.Tests/Common/StateMachine/CircuitBreakerTests.cs |
Max transitions, cycle detection, degraded mode, reset, histogram |
Orkeon.Infrastructure.Tests/Configuration/CircuitBreakerPolicyFactoryGraphTests.cs |
graph: → policy: presets, overrides, fallback |
Orkeon.Scripting.Cli.Tests/Forge/ForgeStateMachineTests.cs |
The forge cycle's legal moves |
dotnet test tests/core/Orkeon.Domain.Tests/Orkeon.Domain.Tests.csproj --filter "FullyQualifiedName~StateMachine"