Struct Phase 

pub struct Phase {

    pub name: String,
    pub instruction: PhaseInstruction,
    pub tools_enabled: Option<Vec<String>>,
    pub guard: Option<StatePredicate>,
    pub on_enter: Option<SessionHook>,
    pub on_exit: Option<SessionHook>,
    pub transitions: Vec<Transition>,
    pub terminal: bool,
    pub modifiers: Vec<InstructionModifier>,
    pub prompt_on_enter: bool,
    pub on_enter_context: Option<EnterContextFn>,
    pub needs: Vec<String>,
    pub requires: Vec<String>,
    pub preparations: Vec<PhasePreparation>,
    pub presents: Vec<String>,
    pub clear_on_enter: Vec<String>,
}

A conversation phase with instruction, tools, and transitions.

Fields

name: String

Unique name identifying this phase.

instruction: PhaseInstruction

The instruction (system prompt fragment) for this phase.

tools_enabled: Option<Vec<String>>

Tool filter — None means all tools are allowed.

guard: Option<StatePredicate>

Optional guard: phase can only be entered when this returns true.

on_enter: Option<SessionHook>

Async callback executed when entering this phase.

on_exit: Option<SessionHook>

Async callback executed when leaving this phase.

transitions: Vec<Transition>

Ordered list of outbound transitions evaluated by the machine.

terminal: bool

If true, evaluate() always returns None — no transitions out.

modifiers: Vec<InstructionModifier>

Instruction modifiers applied during instruction composition. Evaluated in order, each appends to the resolved instruction.

prompt_on_enter: bool

If true, send turnComplete: true after instruction + context on phase entry, causing the model to generate a response immediately.

on_enter_context: Option<EnterContextFn>

Optional context injection on phase entry. Returns Content to send as client_content (turnComplete: false). Gives the model conversational continuity across phase transitions.

needs: Vec<String>

State keys this phase is responsible for gathering.

Purely informational — does not affect transitions or enforcement. The ContextBuilder reads these from session:phase_needs to append a “[Gathering] key1, key2” line to the instruction, so the model knows what to focus on.

requires: Vec<String>

State keys that must exist before this phase can be entered.

Unlike needs, these are enforced by the phase machine. A transition targeting this phase is skipped until every required key is present in state. Use this for authoritative facts that must be materialized before the model is allowed to operate in the phase.

preparations: Vec<PhasePreparation>

Effects that can run before this phase is entered to satisfy requires.

presents: Vec<String>

Semantic concepts this phase presents to the user.

On phase entry the machine writes presented:<concept> = true to state. This lets flows distinguish “the model has collected a yes” from “the user acknowledged this specific concept after it was presented”.

clear_on_enter: Vec<String>

State keys to clear when this phase is entered.

Useful for removing stale acknowledgements or intents gathered before the phase’s presented concepts are valid.

Implementations

impl Phase

pub fn new(name: &str, instruction: &str) -> Self

Create a minimal non-terminal phase with a static instruction and defaults.

pub fn presented_key(concept: &str) -> String

State key used to mark that a concept has been presented.

pub fn is_presented(state: &State, concept: &str) -> bool

Whether a semantic concept has been presented in this conversation.

pub fn missing_requirements(&self, state: &State) -> Vec<String>

Required state keys that are not currently present.