Struct PhaseMachine 

pub struct PhaseMachine { /* private fields */ }

Evaluates transitions and manages phase entry/exit lifecycle.

Implementations

impl PhaseMachine

pub fn new(initial: &str) -> PhaseMachine

Create a new machine with the given initial phase name.

The initial phase must be registered via add_phase before calling validate.

pub fn set_clock(&mut self, clock: Arc<dyn Clock>)

Read phase durations from clock instead of the system clock.

Restarts the current phase’s timer at the new clock’s now. The runtime installs the session state’s clock here when it builds the session.

pub fn add_phase(&mut self, phase: Phase)

Register a phase. Overwrites any existing phase with the same name.

pub fn current(&self) -> &str

The name of the current phase.

pub fn current_phase(&self) -> Option<&Phase>

A reference to the current Phase, if it exists in the registry.

pub fn history(&self) -> &VecDeque<TransitionRecord>

The transition history (oldest first, capped at 100 entries).

pub fn describe_navigation(&self, state: &State) -> String

Generate a structured navigation context block giving the model awareness of where it is in the conversation flow.

The output includes the current phase and its goal, recent phase history, any state keys still needed, and possible transitions.

pub fn evaluate(&self, state: &State) -> Option<(&str, usize)>

Evaluate transitions from the current phase.

Returns the target phase name and transition index of the first transition whose guard returns true, or None if no transition fires (or the current phase is terminal / missing).

This method is pure — it does not modify state or execute callbacks.

pub fn evaluate_for_transition( &self, state: &State, ) -> Option<TransitionEvaluation>

Evaluate transitions from the current phase, preserving blocked targets that declare preparations.

pub async fn prepare_target( &self, target: &str, state: &State, writer: &Arc<dyn SessionWriter>, ) -> bool

Run preparation effects declared by a target phase, then report whether all target requirements are now satisfied.

pub async fn transition( &mut self, target: &str, state: &State, writer: &Arc<dyn SessionWriter>, turn: u32, trigger: TransitionTrigger, transcript_window: &TranscriptWindow, ) -> Option<TransitionResult>

Execute a transition: run on_exit for the current phase, update current, run on_enter for the new phase, record history, and return the TransitionResult for the new phase.

Returns None if the target phase does not exist.

pub fn current_phase_duration(&self) -> Duration

Returns how long the machine has been in the current phase.

pub fn active_tools(&self) -> Option<&[String]>

Active tools filter for the current phase.

Returns None when all tools are allowed, or Some(slice) with the explicitly enabled tool names.

pub fn validate(&self) -> Result<(), ConfigError>

Validate the machine configuration.

Checks:

• At least one phase is registered.
• The initial phase exists.
• Every transition target references an existing phase.