Struct Agent 

pub struct Agent { /* private fields */ }

Implementations

impl Agent

pub fn new(cfg: AgentConfig) -> Agent

pub fn steer(&self, m: AgentMessage)

Queued for injection at the next turn start (this run or a later one).

pub fn set_plan_mode(&mut self, on: bool)

Toggle plan mode: flips the shared handle and recomposes system from base_system — appending PLAN_SECTION when on, restoring the base prompt exactly when off. Takes effect on the NEXT run (the in-flight one cloned system into its LoopConfig at start). Not persisted.

pub fn set_model(&mut self, model: String) -> Result<()>

Swaps the model mid-conversation (takes effect on the next run) and logs a ModelChange entry when a session is open. The new id’s [models.<id>] profile re-points endpoint/base_url/api_key by settling on the launch provider first, so an unmapped id — and a switch back to a previous model — falls back to it (the switch is reversible).

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

Current reasoning effort (None = send nothing).

pub fn set_effort(&mut self, effort: Option<String>) -> Result<()>

Swaps the reasoning effort mid-conversation (next run) and logs an EffortChange entry when a session is open. None clears it.

pub fn steer_sender(&self) -> UnboundedSender<AgentMessage>

Sender clone for steering while run holds the &mut borrow (UI tasks).

run_loop hands the lent channels back at the end of every run, so a clone taken once stays valid across runs and a message sent while a run is in flight — even one the loop never drained — reaches the next run. (Only an error exit reboots the channels, invalidating old clones.)

pub fn follow_up(&self, m: AgentMessage)

Runs after the loop would stop.

pub fn follow_up_sender(&self) -> UnboundedSender<AgentMessage>

Sender clone for injecting a follow-up while run holds the &mut borrow (the mirror of Agent::steer_sender, for a UI/actor task that cannot reach follow_up directly).

pub fn cancel(&self)

pub fn cancel_token(&self) -> CancellationToken

Token for the run in flight or the next one; re-acquire after each run() (a fresh token is minted at the end of every run).

pub fn hooks(&self) -> &HooksSet

The hook set, exposed so the actor can run the inbound policy (HooksSet::before_inbound) while run holds the &mut borrow.

pub async fn run( &mut self, user_text: &str, sink: UnboundedSender<AgentEvent>, ) -> Result<StopReason, LoopError>

pub fn messages(&self) -> &[AgentMessage]

pub fn notify(&mut self, content: String) -> Result<AgentMessage>

Record an inbound peer message into the conversation without starting a turn (the Request::Notify semantic): persist it as a user message and push it onto the context, so the next run sees it. Returns the recorded message so the actor can surface it. Idle-only — the actor routes a Notify that arrives mid-run through steering instead.

pub async fn side_ask(&self, text: &str) -> Result<SideAnswer, LoopError>

Answer text tool-free, from the current context, as a one-off side call.

CLONES ctx, appends the (framed) question, runs the raw stream_fn once with an EMPTY tool list, and folds TextDelta → text until Done (capturing usage). self.ctx and self.session are never mutated or appended — hence &self, so it stays callable while the actor holds &mut Agent for a run.

Errors become LoopError::Stream: a stream Error, or a call that ended with no text. No retry loop of its own — it inherits whatever retry/idle-timeout the configured stream_fn adapter applies internally, exactly as crate::compaction::summarize does. No cancel path in v1.

pub fn side_handle(&self) -> SideHandle

A read-only handle the actor takes before a run borrows the agent, so a mid-run GetHistory/SideAsk is answered from the context snapshot run_loop republishes each turn, instead of waiting for the whole run. See SideHandle.

pub async fn compact( &mut self, instructions: Option<&str>, ) -> Result<CompactOutcome, String>

Summarize the older part of the conversation in place: keep the newest messages per CompactionPolicy and replace the rest with a single summary message. instructions focuses the summary (the /compact <prompt> argument).

When a session is open, the boundary is persisted (crate::session::SessionEntry::Compaction), so a resumed session rebuilds to the same summary + kept view instead of re-expanding.

pub fn session_path(&self) -> Option<&Path>

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

The session’s stable id (from its Header), if a session is open. The address a SessionHandle’s frames carry.