Struct GoalRuntimeHandle 

pub struct GoalRuntimeHandle { /* private fields */ }

Per-session goal lifecycle manager.

Drives auto-continuation, status transitions, and steering prompt injection. All mutations go through with_goal_state which serializes access via a dedicated state lock, preventing external set/clear calls from interfering with continue_if_idle.

Implementations

impl GoalRuntimeHandle

pub fn new(initial_goal: Option<SessionGoal>) -> Self

Creates a new runtime handle with an optional initial goal.

pub fn get_goal(&self) -> Option<SessionGoal>

Returns the current goal, if any.

pub fn set_session_id(&self, session_id: impl Into<String>)

Binds this runtime to a session id and rewrites any loaded goal to match.

pub fn set_objective( &self, objective: String, token_budget: Option<i64>, ) -> SessionGoal

Sets or replaces the goal.

pub fn set_objective_with_short_description( &self, objective: String, short_description: Option<String>, token_budget: Option<i64>, ) -> SessionGoal

Sets or replaces the goal with an optional compact UI label.

When a goal already exists, mutates it in place (same goal_id) and re-activates it — used by host/SDK set_goal. Model create_goal must call [create_new_goal] so terminal goals get a fresh id.

pub fn create_new_goal( &self, objective: String, short_description: Option<String>, token_budget: Option<i64>, ) -> SessionGoal

Creates a brand-new active goal (new goal_id), replacing any prior goal.

Caller must ensure there is no unfinished goal when this is used from the model-facing create_goal tool.

pub fn update_goal(&self, goal: SessionGoal)

Updates the stored goal (used after status transitions).

pub fn clear_goal(&self)

Clears the current goal.

pub fn update_checklist(&self, tasks: Vec<GoalTask>) -> Option<SessionGoal>

Updates the checklist on the current goal. Returns the updated goal if successful.

pub fn update_task_status( &self, task_id: usize, status: TaskStatus, ) -> Option<SessionGoal>

Updates a single task’s status in the goal checklist.

pub fn start_turn(&self)

Starts turn accounting for the active goal.

pub fn record_tokens(&self, delta: i64) -> bool

Records token usage during a turn.

pub fn finish_turn(&self)

Finishes turn accounting and updates the stored goal.

pub fn record_blocked_turn(&self, reason: &str) -> bool

Transitions the goal to Blocked after consecutive blocked turns.

pub fn mark_usage_limited(&self)

Transitions the goal to UsageLimited.

pub fn continue_if_idle(&self) -> Option<String>

If the goal is active and should auto-continue, returns a steering continuation prompt to inject into the conversation. Acquires the state lock to prevent race conditions with concurrent set/clear operations.

pub fn budget_limit_prompt(&self) -> Option<String>

Returns a budget-limit steering prompt if the budget is exceeded.

pub fn objective_updated_prompt(&self) -> Option<String>

Returns an objective-updated steering prompt.

pub fn set_auto_continue(&self, enabled: bool)

Enables or disables auto-continuation.

pub fn is_terminal(&self) -> bool

Returns true if the goal is in a terminal state.