Skip to main content

tea_kernel/
state.rs

1use thiserror::Error;
2
3/// Explicit lifecycle state of one kernel run.
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub enum RunState {
6    /// No operation has started.
7    Idle,
8    /// Durable session context is being loaded and frozen.
9    PreparingContext,
10    /// One immutable model request is being streamed.
11    StreamingModel,
12    /// Complete model tool calls are being committed and validated.
13    PlanningToolCalls,
14    /// A validated invocation is being evaluated by policy.
15    EvaluatingPolicy,
16    /// The run is durably paused for a caller decision.
17    WaitingApproval,
18    /// One authorized tool is executing.
19    ExecutingTool,
20    /// Durable turn output and checkpoint are being committed.
21    CommittingTurn,
22    /// The run completed normally.
23    Completed,
24    /// The run was cooperatively cancelled.
25    Cancelled,
26    /// The run was interrupted at a recoverable boundary.
27    Interrupted,
28    /// The run failed before a safe continuation boundary.
29    Failed,
30}
31
32impl RunState {
33    /// Validates and applies one explicit transition.
34    ///
35    /// # Errors
36    ///
37    /// Returns an error when the target is not legal from this state.
38    pub fn transition(self, next: Self) -> Result<Self, StateTransitionError> {
39        let valid = matches!(
40            (self, next),
41            (Self::Idle, Self::PreparingContext)
42                | (
43                    Self::PreparingContext | Self::CommittingTurn,
44                    Self::StreamingModel
45                )
46                | (
47                    Self::PreparingContext | Self::EvaluatingPolicy,
48                    Self::WaitingApproval
49                )
50                | (
51                    Self::StreamingModel,
52                    Self::PlanningToolCalls | Self::CommittingTurn
53                )
54                | (
55                    Self::PlanningToolCalls | Self::ExecutingTool,
56                    Self::EvaluatingPolicy
57                )
58                | (
59                    Self::PlanningToolCalls
60                        | Self::EvaluatingPolicy
61                        | Self::WaitingApproval
62                        | Self::ExecutingTool,
63                    Self::CommittingTurn
64                )
65                | (
66                    Self::EvaluatingPolicy | Self::WaitingApproval,
67                    Self::ExecutingTool
68                )
69                | (Self::CommittingTurn, Self::Completed)
70                | (_, Self::Cancelled | Self::Interrupted | Self::Failed)
71        );
72        valid.then_some(next).ok_or(StateTransitionError)
73    }
74
75    /// Returns whether this state is terminal for the current invocation.
76    #[must_use]
77    pub const fn is_terminal(self) -> bool {
78        matches!(
79            self,
80            Self::WaitingApproval
81                | Self::Completed
82                | Self::Cancelled
83                | Self::Interrupted
84                | Self::Failed
85        )
86    }
87}
88
89/// Explicit lifecycle state of one model/tool turn.
90#[derive(Debug, Clone, Copy, PartialEq, Eq)]
91pub enum TurnState {
92    /// The immutable request has not been built.
93    Preparing,
94    /// The provider stream is active.
95    Streaming,
96    /// Complete tool declarations are being processed.
97    ProcessingTools,
98    /// A durable checkpoint has been committed.
99    Checkpointed,
100    /// The turn ended before a safe checkpoint.
101    Interrupted,
102}
103
104/// Invalid runtime-state transition.
105#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
106#[error("kernel state transition is invalid")]
107pub struct StateTransitionError;