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 rewind_store_handle(&self) -> Arc<Mutex<RewindStore>>

Shared rewind store (write tools note dirty paths through this handle).

pub fn rebind_rewind_store(&self)

Rebind rewind store to the live session id (after start_session).

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 and notifies live clients.

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

Sets or updates the session goal with a compact UI label.

pub fn clear_goal(&self)

Clears the current session goal.

Live UIs typically clear their chip optimistically when the user requests clear; no terminal GoalUpdated is published (that would look like a successful complete).

pub fn update_goal(&self, goal: SessionGoal)

Updates the stored goal (used after status transitions) and notifies clients.

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. Exploration tools + the session plan markdown file are available; project writes and commands are blocked.

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 session catalog filter for skills.

Empty skills means all discovered skills are catalog-active (default). Non-empty restricts the Available Skills catalog to those ids/names. Never injects skill instruction bodies into the prompt.

When a skill has a harness pack under {data_dir}/harnesses/<id>/, applies soft graph allowlists, loop max_turns / token_budget, and harness card text.

pub fn effective_max_auto_continue_turns(&self) -> u32

Effective max auto-continue turns (harness pack overrides goals config when set).

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

Developer harness card for the active pack(s), if any.

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.

After a successful turn, if a thread goal is still active, runs automatic continuation turns (idle lifecycle) until the goal stops, the auto-continue limit is hit, plan mode is on, or the user has pending input.

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 compact_now(&mut self) -> Result<CompactOutcome>

Force-compact live conversation history using the session’s own model.

Summarizes older turns, replaces the live message list, and emits AutoCompactStarted / AutoCompactCompleted (or Failed) events.

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. Also restores project files to the pre-turn state of the first dropped user prompt (session rewind).

Caller should then send_turn with the new text (or leave the prompt in the input for the user to edit).

keep_user_turns = 0 keeps only system/developer preamble.

pub fn list_rewind_points(&self) -> Vec<RewindPointMeta>

List rewind checkpoints (user-turn snapshots) for the live session.

pub fn rewind_store_points_path(&self) -> PathBuf

Filesystem restore summary from the last restore_to is not retained; use Self::rewind_to_user_turns which restores as a side effect.

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 retain_tools<F>(&mut self, pred: F)

where F: FnMut(&str) -> bool,

Keep only tools whose names satisfy pred on the live session executor.

Used by host tool profiles after start (goal/skill tools may re-register). No-ops when the executor Arc is shared.

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.