Struct CodingAgent 

pub struct CodingAgent { /* private fields */ }

A coding agent: drives run_turn over the built-in tools, one turn at a time, keeping the history in a caller-visible Session.

Implementations

impl CodingAgent

pub fn new( provider: Arc<dyn ModelProvider>, config: CodingAgentConfig, ) -> Result<Self, CodingAgentError>

A fresh agent with an empty session. The workspace is canonicalized for tool scoping; the system prompt defaults to the built-in template rendered by [crate::prompt::render_system] unless config.system replaces it. A base prompt that fails to render fails the construction.

pub fn from_session( provider: Arc<dyn ModelProvider>, config: CodingAgentConfig, session: Session, ) -> Result<Self, CodingAgentError>

A fresh agent resuming session (e.g. from CodingAgent::load_session_from); the next turn continues the prior history.

The conversation’s environment report is conversation state: a session carrying one reuses its bytes verbatim, whatever the config would render fresh — the report’s date names the conversation’s start, and a resume that re-stamped it would rewrite the system prompt and break the provider’s prompt cache for the whole prefix. A session without one (a conversation from before the report existed) stamps the config’s render and carries it forward.

pub fn set_commit_hook(&mut self, hook: Option<CommitHook>)

Installs the per-stream checkpoint hook on the engine (see rhema_core::CommitHook); None disables it. A driver that persists the session sets this so a crash mid-turn — inside a tool call (a committed intent, which the next turn’s revive closes) or mid-stream, first stream included — leaves a resumable session at the last boundary rather than no record at all.

pub fn session(&self) -> &Session

The conversation so far.

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

The rendered system prompt this agent stamps into every request, or None when the caller supplied none.

pub fn transcript_stats(&self) -> Option<TranscriptStats>

The transcript’s compaction benchmark snapshot — request counts, flushes, block size, and the providers’ own prompt-cache hit rate — when the transcript is on. None with it off.

pub fn carry_transcript_stats(&mut self, saved: &TranscriptStats)

Folds a saved session’s benchmark counters into the transcript mirror, when the transcript is on: a resumed session’s stats keep reading as one run, pre-resume requests included. No-op with the transcript off — there is nothing to continue.

pub fn transcript_sections(&self) -> Vec<Section>

The mirror’s committed sections, oldest first: what a session save carries so the next session adopts the compaction instead of re-deriving it and re-paying the worker. Empty with the transcript off.

pub fn adopt_transcript_sections(&mut self, sections: Vec<Section>)

Hands a saved session’s sections to the mirror. They wait for the first request, which adopts them when they tile the resumed log and drops them for any rebuild. No-op with the transcript off.

pub fn reset_transcript_stats(&mut self)

Zeroes the transcript’s benchmark counters, when the transcript is on: a conversation cleared mid-agent starts its accounting over, and the stats describe one conversation, not the agent’s lifetime.

pub fn session_mut(&mut self) -> &mut Session

Mutable access between turns; the engine owns the history only inside a turn.

pub async fn turn( &mut self, input: impl Into<String>, sink: &mut dyn EventSink, approval: Arc<dyn Approval>, ) -> Result<ModelOutput, CodingAgentError>

One turn: push the user input, loop steps until the model stops requesting tools (capped at max_turn_steps), with approval gating the side-effecting tools. Appends to the session in place; the hook is cleared on the way out, success or failure. A history entering with unanswered calls — a crash resume — revives first, so the model sees a closed round, not a dangling one.

pub async fn turn_with_cancel( &mut self, input: impl Into<String>, sink: &mut dyn EventSink, approval: Arc<dyn Approval>, cancelled: Arc<AtomicBool>, ) -> Result<ModelOutput, CodingAgentError>

Self::turn with a driver-held cancel flag: flipping cancelled mid-turn asks in-flight tools to stop (the executor polls it) and the next resolution to refuse. A driver whose stop arrives from outside the turn — a frontend’s stop message, a disconnected socket — holds one flag per turn and passes it here; the plain Self::turn builds a flag nobody else can reach.

pub async fn turn_message( &mut self, message: Message, sink: &mut dyn EventSink, approval: Arc<dyn Approval>, ) -> Result<ModelOutput, CodingAgentError>

Self::turn over a whole Message: the entry point for inputs carrying image blocks beside the text. Steering stays text — a steered nudge is a sentence, not a screenshot.

pub async fn turn_message_with_cancel( &mut self, message: Message, sink: &mut dyn EventSink, approval: Arc<dyn Approval>, cancelled: Arc<AtomicBool>, ) -> Result<ModelOutput, CodingAgentError>

Self::turn_message with Self::turn_with_cancel’s cancel flag — the full form both convenience wrappers fold into.

pub async fn retry_turn_with_cancel( &mut self, sink: &mut dyn EventSink, approval: Arc<dyn Approval>, cancelled: Arc<AtomicBool>, ) -> Result<ModelOutput, CodingAgentError>

The failed request again: no new input message — the step loop runs on the history exactly as the failed turn left it, so the same request goes out. A first-request failure re-issues the identical request; a mid-turn failure re-issues the step that failed, with the committed steps still in view (the model sees what already ran and continues from there — no committed tool call re-executes behind the model’s back). A history entering with unanswered calls — a commit-hook failure after an intent landed — revives first, like any turn. Approval and cancel wire in as in Self::turn_message_with_cancel.

pub fn save_session_to(&self, path: &impl AsRef<Path>) -> Result<()>

Writes the session as pretty JSON to path: 0600, landed through a temp file and renamed, so nothing conversation-shaped is ever world-readable and a crash mid-save leaves the previous checkpoint whole. This is the one store in the tree that holds the full history; it rides the same privacy helpers as every other (see rhema_config::privacy).

pub fn load_session_from(path: &impl AsRef<Path>) -> Result<Session>

Reads a session written by CodingAgent::save_session_to.