Struct Conversation 

pub struct Conversation<M: CompletionModel> { /* private fields */ }

An agent loop bound to a single CompletionModel, with history, tool registry, and middleware chain configured up front. Construct via Conversation::builder.

Two entry points drive a turn: Conversation::run for one-shot flows that materialise a RunOutcome, and Conversation::stream for code that wants to consume each StreamChunk as it lands. Both extend the conversation’s history with the run’s new_messages exactly once.

Aborts are not errors. RunConfig::cancellation firing, RunConfig::timeout elapsing, and middleware/tool returning Terminate all surface as Ok(_) carrying FinishReason::Aborted — never as Err(EngineError::_). Only model / tool-registry / context errors produce an Err. See EngineError for the failure surface.

Implementations

impl<M: CompletionModel + Send + Sync> Conversation<M>

pub fn builder(model: M) -> ConversationBuilder<M>

Start a ConversationBuilder for model. Equivalent to ConversationBuilder::new(model) and is the canonical entry point — most code should never call ConversationBuilder::new directly.

pub fn history_messages(&self) -> &[Message]

Read-only view of the conversation history. Useful for asserting in tests and for callers who want to inspect or persist the conversation state outside of Conversation::run / Conversation::stream.

pub fn history_push(&mut self, message: Message)

Append a message to history without going through a run. Lets callers seed history (e.g. for resume scenarios or tests that need to overflow the compaction budget before issuing a real turn). Compaction is not triggered here — that happens on the next Conversation::run / Conversation::stream call.

pub fn snapshot(&self) -> ConversationSnapshot

Persistable snapshot of this conversation’s logical state: the message vector and the parallel pin mask. Pair with ConversationBuilder::from_snapshot to rebuild a Conversation after a restart — the model, tools, and middlewares must be re-supplied at resume time.

pub fn active_tool_names(&self) -> Vec<String>

Names of every tool currently active for this conversation.

Useful for asserting in tests and for surfacing the effective tool set after with_capabilities filtering.

pub async fn run( &mut self, user_input: impl Into<String>, ) -> Result<RunOutcome, EngineError<M::Error>>

Non-streaming convenience for one-question / one-answer flows (CLI tools, notebooks, batch evaluation). Drains the underlying Conversation::stream and materialises a RunOutcome summarising the run.

Errors from the model, tools, or context management surface as Err(EngineError), exactly as they would on the streaming path. Aborted runs (timeout, cancellation, hook/tool Terminate) are not errors — they return Ok(RunOutcome) with finish_reason = FinishReason::Aborted(_). The caller decides whether to treat that as success or failure.

History is extended with the run’s new_messages exactly once, the same way it is on the streaming path.

pub async fn stream( &mut self, user_msg: impl Into<String>, ) -> Result<RunStream<'_, M>, EngineError<M::Error>>

Drive a turn and yield each StreamChunk as it lands — for callers that want to render tokens, observe tool calls, or thread events through their own UI as the run unfolds.

The returned RunStream always terminates with a StreamChunk::RunFinished, whether the run completed normally or aborted (cancellation, timeout, or hook/tool Terminate). Aborts surface as RunFinished carrying FinishReason::Aborted — they are never Err. The same failure surface as Conversation::run applies otherwise: model, tool-registry, and context errors yield Err(EngineError).

History is extended with the run’s new_messages exactly once, keyed off the terminal RunFinished chunk — pair this with Conversation::history_messages only after the stream has fully drained.

If History::compact_if_needed fires before the engine starts a StreamChunk::HistoryCompacted is yielded as the first chunk, carrying the same RunId every subsequent engine chunk uses.