Struct History 

pub struct History { /* private fields */ }

Owns the message vector backing a single conversation, plus the budget and pin mask that govern how compaction reduces it.

Lifecycle: append turns with add_message / extend, inspect with messages, pin survivors with pin_last / pin_at / pin_with_tool_result, and call compact_if_needed before each outgoing ChatRequest to hold the history under the configured budget. Restore from a ConversationSnapshot via from_messages.

The façade Conversation wires one of these automatically — touch this type directly only when driving advanced::run_chat or building tests.

Implementations

impl History

pub fn builder(max_tokens: usize) -> HistoryBuilder

Begin configuring a new manager with max_tokens as the budget compact_if_needed will hold the history under. Defaults: TruncateStrategy for reduction, CharTokenizer (len() / 4) for sizing, four preserved tail messages.

pub fn from_messages( builder: HistoryBuilder, messages: Vec<Message>, pinned: Vec<bool>, ) -> Result<History, FromMessagesError>

Restore a History whose history is messages and whose pin mask is pinned. The two vectors must have the same length; otherwise a FromMessagesError::LengthMismatch is returned. All other configuration (budget, strategy, tokenizer, preserved tail size) comes from builder — pass the same configuration the original conversation used so compaction behaves consistently across resumes.

impl History

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

Append message to the history with pinned = false. Use pin_last immediately after the call to mark it as a survivor.

pub fn estimated_tokens(&self) -> usize

Approximate token cost of the entire history under the configured Tokenizer. The accuracy of this number is only as good as the tokenizer wired into the builder — under the default CharTokenizer it is a len() / 4 ballpark.

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

Borrow the current history slice. Indices into this slice align with pinned.

pub fn extend(&mut self, new_messages: Vec<Message>)

Append every message in new_messages, all with pinned = false. The engine uses this after a turn to fold the assistant reply (and any tool results) back into the history.

pub fn pinned(&self) -> &[bool]

Pinned-state slice, parallel to Self::messages. Useful for tests; production callers normally interact via the pin_* helpers and inspect Self::is_pinned.

pub fn is_pinned(&self, idx: usize) -> bool

Whether messages[idx] is currently pinned. Out-of-bounds indices return false rather than panicking.

pub fn pin_last(&mut self)

Pin the most recently added message so it survives every future compaction. No-op when the history is empty.

Indices are not stable across compactions: a pin_last() made before compaction stays pinned (the strategy keeps it), but its numeric index in the new history may shift. Re-derive indices (or rely on pin_last) after compaction runs.

pub fn pin_at(&mut self, idx: usize)

Pin the message at idx. Panics on out-of-bounds, matching the convention of Vec::index.

pub fn unpin_at(&mut self, idx: usize)

Clear the pin on the message at idx. Panics on out-of-bounds.

pub fn pin_with_tool_result(&mut self, idx: usize)

Pin idx together with every message that pairs with it via a tool_call ↔ tool_result link. Without this, pinning a lone Assistant ToolCall (or a lone User ToolResult) and then letting compaction run would strand the partner — most providers reject that as a malformed history.

Resolution rules:

• If messages[idx] is an Assistant with ToolCall blocks, any User message containing a ToolResult whose call_id matches one of those calls is also pinned.
• If messages[idx] is a User with ToolResult blocks, any Assistant message containing a ToolCall whose id matches is also pinned.
• Messages without tool blocks are pinned alone (effectively a pin_at).

Panics on out-of-bounds. The lookup scans the full history but each message is examined at most once.

pub async fn compact_if_needed( &mut self, ) -> Result<Option<CompactionReport>, CompactionError>

Run the configured CompactionStrategy when estimated_tokens reaches the budget; otherwise return Ok(None) and leave the history untouched.

On success returns Ok(Some(report)) describing the before/after counts and the strategy name. The engine emits StreamChunk::HistoryCompacted carrying the same fields so observability middlewares can correlate the compaction with the run that triggered it.

Errors propagate from the strategy (commonly CompactionError::SummarizationFailed when the summarizer model itself fails). CompactionError::NotEnoughHistory surfaces when the history has fewer messages than preserve_n_last and there is nothing to drop.