Struct AgentRuntime 

pub struct AgentRuntime { /* private fields */ }

The core agent runtime that manages sessions, turns, approvals, and events.

Implementations

impl AgentRuntime

pub fn new(options: AgentRuntimeOptions) -> Self

Creates a new runtime from the given options.

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

Returns all agent events recorded so far. Returns the current session goal, if any.

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

Sets or updates the session goal.

pub fn clear_goal(&self)

Clears the current session goal.

pub fn update_goal(&self, goal: SessionGoal)

Updates the stored goal (used after status transitions).

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

Updates the goal checklist (replaces all tasks).

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

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

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

Returns a continuation steering prompt if the goal is active and should auto-continue.

pub fn goals_config(&self) -> GoalsConfig

Returns the goals configuration.

pub fn goal_runtime(&self) -> &Arc<GoalRuntimeHandle>

Returns a reference to the goal runtime handle.

pub fn agent_mode(&self) -> AgentMode

Returns the current agent mode.

pub fn enter_plan_mode(&self)

Enters Plan mode. Only read-only tools will be available, and the model is instructed to propose a plan via <proposed_plan> tags.

pub fn exit_plan_mode(&self)

Exits Plan mode and returns to normal execution.

pub fn feed_plan_text(&self, text: &str) -> Vec<ProposedPlan>

Feeds a text delta into the plan parser. Returns any completed plans.

pub fn drain_plans(&self) -> Vec<ProposedPlan>

Drains any pending plans from the parser (call at end of turn).

pub fn is_parsing_plan(&self) -> bool

Returns true if the parser is currently inside a <proposed_plan> block.

pub fn has_pending_user_input(&self) -> bool

Returns true if a user message is pending (set when send_turn is called while the runtime is busy with auto-continuation).

pub fn set_pending_user_input(&self, pending: bool)

Marks that a user message is pending.

pub fn events(&self) -> &[AgentEvent]

Returns all agent events recorded so far.

pub fn session_id(&self) -> &SessionId

Returns the current session id.

pub fn session_title(&self) -> Option<&str>

Returns the session title, if one has been derived.

pub fn add_context_packet(&mut self, packet: ContextPacket)

Adds a context packet to the session and emits a ContextUpdated event.

pub fn clear_context_packets(&mut self)

Clears all context packets and emits a ContextUpdated event.

pub fn context_packets(&self) -> &[ContextPacket]

Returns the current context packets.

pub fn set_active_skills(&mut self, skills: Vec<String>)

Sets the active skills for this session and emits a ContextUpdated event.

pub fn list_models(&self) -> Vec<ModelOption>

Lists available model options from the loaded configuration.

pub fn model_selection(&self) -> (&str, &str)

Current (provider_id, model_name) selection for this runtime.

pub fn set_model( &mut self, provider: impl Into<String>, model: impl Into<String>, )

Changes the selected model and emits a ContextUpdated event.

pub fn set_model_provider( &mut self, loaded_config: LoadedConfig, model_provider: Arc<dyn ModelProvider>, )

Replaces the runtime configuration and provider used by subsequent turns.

pub fn register_host_tool(&mut self, tool: Arc<dyn Tool>) -> Result<()>

Registers a host-provided tool with the runtime’s tool executor. Creates a default executor if none exists yet.

pub fn stream_events(&self) -> Receiver<RuntimeEvent>

Returns a broadcast receiver for RuntimeEvents.

pub fn cancel_turn(&self)

Cancels the currently running turn.

pub fn resolve_approval(&self, decision: ApprovalDecision) -> bool

Resolves a pending approval by id. Returns true if found.

pub fn resolve_question(&self, response: QuestionResponse) -> bool

Resolves a pending interactive question by id. Returns true if found.

pub fn resolve_plan_review(&self, response: PlanReviewResponse) -> bool

Resolves a pending plan review by invocation id. Returns true if found.

pub fn approval_resolver(&self) -> ApprovalResolver

Returns an ApprovalResolver handle for external approval resolution.

pub fn question_resolver(&self) -> QuestionResolver

Returns a QuestionResolver handle for external question resolution.

pub fn plan_review_resolver(&self) -> PlanReviewResolver

Returns a PlanReviewResolver handle for external plan-review resolution.

pub fn sudo_password_resolver(&self) -> SudoPasswordResolver

Returns a SudoPasswordResolver for interactive sudo prompts.

pub fn resolve_sudo_password(&self, response: SudoPasswordResponse) -> bool

pub fn turn_canceller(&self) -> TurnCanceller

Returns a TurnCanceller handle for external cancellation.

pub fn start_session(&mut self) -> Result<SessionId>

Starts a new session (or restarts if one is already active). Returns the session id.

pub async fn send_turn_with_parts( &mut self, task: String, content_parts: Vec<ContentPart>, thinking_override: Option<ThinkingConfig>, ) -> Result<ModelResponse>

Sends a user task to the agent and waits for the full response. Starts a session automatically if one is not active. Sends a user turn with optional multimodal content parts.

When content_parts is non-empty, the message is created as a multimodal user message containing both text and images.

pub async fn submit_task(&mut self, task: String) -> Result<ModelResponse>

pub async fn send_turn(&mut self, task: String) -> Result<ModelResponse>

Sends a plain text user turn (no images).

pub async fn rewind_to_user_turns( &mut self, keep_user_turns: usize, ) -> Result<usize>

Rewind live conversation history for an edited past user message.

Keeps the first keep_user_turns user turns (and their assistant/tool follow-ups), drops everything after, and truncates recorded session events the same way. Caller should then send_turn with the new text.

keep_user_turns = 0 keeps only system/developer preamble.

pub fn snapshot_session(&mut self) -> Result<SessionSnapshot>

Creates a SessionSnapshot of the current session state for persistence.

pub async fn snapshot_session_async(&mut self) -> Result<SessionSnapshot>

Creates and persists a session snapshot without blocking the async runtime.

pub fn tool_executor(&self) -> Option<Arc<ToolExecutor>>

Returns the configured tool executor, if any.

pub fn session_title_handle(&self) -> SessionTitleHandle

Returns the session-local handle used by the title tool. SDK tooling reloads use this to keep the built-in title capability installed.

pub fn set_tool_executor(&mut self, executor: Arc<ToolExecutor>)

Replaces the session tool executor (e.g. after installing WASM plugins).

pub fn set_security_config(&mut self, security: SecurityConfig) -> Result<()>

Updates the security configuration used by the tool executor and the runtime’s loaded config. No-op when no executor has been created yet.