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 title_after_turns(&self) -> usize

Assistant turns before the auto-titler fires (0 = off) — the resolved [session] title_after_turns this agent was built with (W031).

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 set_title(&mut self, title: &str) -> Result<()>

Give this session a name: append a Title entry (last write wins) and mirror it in memory. The EXPLICIT rename path — /rename on both human surfaces, --title, and crate::protocol::Request::SetTitle — never calls a model.

Appends BEFORE the in-memory write, deliberately (the Agent::set_model rationale, “a failed append must not leave the agent and the session disagreeing”): if the append fails the caller gets the io::Error and Agent::title is unchanged, so a UI never claims a name the file does not have.

Errors

The session append’s io::Error, unchanged. The in-memory mirror is NOT updated on failure.

Does not

Sanitize (/rename takes the user’s text verbatim; the AUTO path sanitizes, in crate::title::sanitize), call a model, or refuse an empty string — set_title("") stores an empty title and Agent::title then returns Some("").

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

The session’s current title (None = never titled).

Reads the SESSION first, the in-memory mirror second — and that order is the whole contract. The auto-titler runs inside run_loop, which holds &mut Session and no &mut Agent, so a title it appends lands in the session and NOT in an Agent field; a mirror-only getter would report None right after a successful auto-title, and a UI asking the actor would disagree with the file. Session-first makes the persisted value authoritative; the mirror covers --no-session, where there is no session to ask.

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.