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;