pub struct Session { /* private fields */ }Expand description
A conversation session with full history
Uses Arc<Vec
Implementations§
Source§impl Session
impl Session
Sourcepub fn created_at(&self) -> SystemTime
pub fn created_at(&self) -> SystemTime
Get creation time
Sourcepub fn updated_at(&self) -> SystemTime
pub fn updated_at(&self) -> SystemTime
Get last update time
Sourcepub fn push(&mut self, message: Message)
pub fn push(&mut self, message: Message)
Add a message to the session
Updates the timestamp. For adding multiple messages, prefer push_batch.
Sourcepub fn push_batch(&mut self, messages: Vec<Message>)
pub fn push_batch(&mut self, messages: Vec<Message>)
Add multiple messages in one operation (single timestamp update)
More efficient than multiple push calls when adding many messages.
Sourcepub async fn externalize_media(
&mut self,
blob_store: &dyn BlobStore,
start: usize,
) -> Result<(), BlobStoreError>
pub async fn externalize_media( &mut self, blob_store: &dyn BlobStore, start: usize, ) -> Result<(), BlobStoreError>
Rewrite inline media payloads in-place as BlobRef pointers.
Message count is invariant across this operation — externalize
only swaps inline image/media bytes for opaque blob references.
This is the cross-crate-legitimate rewrite operation that used
to require public messages_mut(); post-C-H1 callers in
meerkat-session go through this typed method.
Does not touch updated_at — externalization is bookkeeping, not
a semantic session mutation.
Sourcepub fn touch(&mut self)
pub fn touch(&mut self)
Explicitly update the timestamp
Call this after bulk operations that don’t update timestamps automatically.
Sourcepub fn has_pending_boundary(&self) -> bool
pub fn has_pending_boundary(&self) -> bool
Whether the conversation has a pending turn boundary.
Returns true if the last message is User or ToolResults, meaning
the conversation is waiting for an assistant turn and run_pending can
resume without a new user message.
Sourcepub fn total_tokens(&self) -> u64
pub fn total_tokens(&self) -> u64
Count total tokens used.
Sourcepub fn total_usage(&self) -> Usage
pub fn total_usage(&self) -> Usage
Get total usage statistics for the session.
Sourcepub fn record_usage(&mut self, turn_usage: Usage)
pub fn record_usage(&mut self, turn_usage: Usage)
Update cumulative usage after an LLM call.
Sourcepub fn append_external_user_content(&mut self, content: ContentInput)
pub fn append_external_user_content(&mut self, content: ContentInput)
Append externally-produced user content to the canonical transcript.
Sourcepub fn append_external_assistant_blocks(
&mut self,
blocks: Vec<AssistantBlock>,
stop_reason: StopReason,
usage: Usage,
)
pub fn append_external_assistant_blocks( &mut self, blocks: Vec<AssistantBlock>, stop_reason: StopReason, usage: Usage, )
Append externally-produced assistant output to the canonical transcript.
Sourcepub fn append_realtime_transcript_event(
&mut self,
event: RealtimeTranscriptEvent,
) -> RealtimeTranscriptApplyOutcome
pub fn append_realtime_transcript_event( &mut self, event: RealtimeTranscriptEvent, ) -> RealtimeTranscriptApplyOutcome
Apply an identity-bearing provider realtime transcript event.
This is the canonical append authority for provider-managed realtime turns: provider item ids, predecessor links, and content segment ids are persisted in session metadata so duplicate websocket delivery, reconnect replay, and causally equivalent event ordering cannot create duplicate or misordered canonical messages.
Sourcepub fn in_flight_realtime_assistant_response_ids(&self) -> Vec<String>
pub fn in_flight_realtime_assistant_response_ids(&self) -> Vec<String>
Return every distinct provider response_id currently staged in the
realtime-transcript metadata that has at least one unmaterialized
assistant item and is not already discarded.
CC4 (Round-4 architectural reconciliation): when the live boundary
signals a barge-in (TurnInterrupted), the projection sink does not
know which provider response_ids have streaming deltas staged in
session metadata. This accessor lets the sink fan
RealtimeTranscriptEvent::AssistantTurnInterrupted events out to
each in-flight response so staged-but-not-yet-materialized transcript
fragments are discarded — preventing them from silently committing
when the next turn’s AssistantTurnCompleted (synthesized by the
CC2 fix in signal_turn_completed) sweeps the materializer.
Order is the [SessionRealtimeTranscriptState::first_seen_order]
projection so callers see deterministic iteration. Items already
materialized or skipped are excluded — only response_ids with at
least one live unmaterialized assistant item are returned.
Sourcepub fn set_system_prompt(&mut self, prompt: String)
pub fn set_system_prompt(&mut self, prompt: String)
Set a system prompt (adds or replaces System message at start)
Sourcepub fn discard_transient_runtime_steer_context(&mut self) -> usize
pub fn discard_transient_runtime_steer_context(&mut self) -> usize
Remove transient active-turn steer context from persisted session state.
Operator steers accepted into an already-running turn are request-local: they should be visible to that turn’s next model boundary, then vanish instead of replaying into later turns after persistence or resume.
Sourcepub fn append_system_context_blocks(
&mut self,
appends: &[PendingSystemContextAppend],
)
pub fn append_system_context_blocks( &mut self, appends: &[PendingSystemContextAppend], )
Append one or more runtime system-context blocks to the canonical system prompt.
Sourcepub fn last_assistant_text(&self) -> Option<String>
pub fn last_assistant_text(&self) -> Option<String>
Get the last assistant message text content.
Concatenates both Text (display) and Transcript (spoken) blocks
in document order, since both lanes project to the same human-readable
stream. Lane provenance is preserved on the underlying AssistantBlock
for callers that need it.
Sourcepub fn tool_call_count(&self) -> usize
pub fn tool_call_count(&self) -> usize
Count tool calls made
Sourcepub fn set_metadata(&mut self, key: &str, value: Value)
pub fn set_metadata(&mut self, key: &str, value: Value)
Set a metadata value
Sourcepub fn backfill_metadata_if_absent(&mut self, key: &str, value: Value) -> bool
pub fn backfill_metadata_if_absent(&mut self, key: &str, value: Value) -> bool
Backfill a missing metadata value without changing updated_at.
This is only for compatibility reads that need to hydrate metadata from
an older projection. Semantic metadata mutations must use
Session::set_metadata so the session timestamp advances.
Sourcepub fn remove_metadata(&mut self, key: &str)
pub fn remove_metadata(&mut self, key: &str)
Remove a metadata value.
Sourcepub fn set_session_metadata(
&mut self,
metadata: SessionMetadata,
) -> Result<(), Error>
pub fn set_session_metadata( &mut self, metadata: SessionMetadata, ) -> Result<(), Error>
Store SessionMetadata in the session metadata map.
Sourcepub fn session_metadata(&self) -> Option<SessionMetadata>
pub fn session_metadata(&self) -> Option<SessionMetadata>
Load SessionMetadata from the session metadata map.
Sourcepub fn set_system_context_state(
&mut self,
state: SessionSystemContextState,
) -> Result<(), Error>
pub fn set_system_context_state( &mut self, state: SessionSystemContextState, ) -> Result<(), Error>
Store durable system-context control state in the session metadata map.
Sourcepub fn system_context_state(&self) -> Option<SessionSystemContextState>
pub fn system_context_state(&self) -> Option<SessionSystemContextState>
Load durable system-context control state from the session metadata map.
Sourcepub fn set_deferred_turn_state(
&mut self,
state: SessionDeferredTurnState,
) -> Result<(), Error>
pub fn set_deferred_turn_state( &mut self, state: SessionDeferredTurnState, ) -> Result<(), Error>
Store durable deferred-turn control state in the session metadata map.
Sourcepub fn deferred_turn_state(&self) -> Option<SessionDeferredTurnState>
pub fn deferred_turn_state(&self) -> Option<SessionDeferredTurnState>
Load durable deferred-turn control state from the session metadata map.
Sourcepub fn set_build_state(&mut self, state: SessionBuildState) -> Result<(), Error>
pub fn set_build_state(&mut self, state: SessionBuildState) -> Result<(), Error>
Store recoverable build-only session state in the session metadata map.
Sourcepub fn build_state(&self) -> Option<SessionBuildState>
pub fn build_state(&self) -> Option<SessionBuildState>
Load recoverable build-only session state from the session metadata map.
Sourcepub fn set_tool_visibility_state(
&mut self,
state: SessionToolVisibilityState,
) -> Result<(), Error>
pub fn set_tool_visibility_state( &mut self, state: SessionToolVisibilityState, ) -> Result<(), Error>
Store durable tool-visibility control state in the session metadata map.
Sourcepub fn tool_visibility_state(
&self,
) -> Result<Option<SessionToolVisibilityState>, Error>
pub fn tool_visibility_state( &self, ) -> Result<Option<SessionToolVisibilityState>, Error>
Load durable tool-visibility control state from the session metadata map.
Sourcepub fn try_tool_visibility_state(
&self,
) -> Result<Option<SessionToolVisibilityState>, Error>
pub fn try_tool_visibility_state( &self, ) -> Result<Option<SessionToolVisibilityState>, Error>
Load durable tool-visibility control state while distinguishing absent metadata from malformed canonical metadata.
Sourcepub fn transcript_history_state(
&self,
) -> Result<Option<TranscriptHistoryState>, Error>
pub fn transcript_history_state( &self, ) -> Result<Option<TranscriptHistoryState>, Error>
Load typed transcript revision state from metadata.
Sourcepub fn validate_transcript_history_state(
&self,
) -> Result<(), TranscriptEditError>
pub fn validate_transcript_history_state( &self, ) -> Result<(), TranscriptEditError>
Validate the retained transcript revision graph, when present.
Sourcepub fn transcript_revision_body(
&self,
revision: &str,
) -> Result<Option<TranscriptRevisionBody>, Error>
pub fn transcript_revision_body( &self, revision: &str, ) -> Result<Option<TranscriptRevisionBody>, Error>
Return the retained immutable body for a transcript revision.
Sourcepub fn transcript_revision_messages(
&self,
revision: &str,
) -> Result<Option<Vec<Message>>, Error>
pub fn transcript_revision_messages( &self, revision: &str, ) -> Result<Option<Vec<Message>>, Error>
Return the ordered messages for a retained transcript revision.
Sourcepub fn apply_transcript_history_state(
&mut self,
state: TranscriptHistoryState,
) -> Result<(), TranscriptEditError>
pub fn apply_transcript_history_state( &mut self, state: TranscriptHistoryState, ) -> Result<(), TranscriptEditError>
Materialize this session projection from a typed transcript history graph.
Sourcepub fn transcript_revision(&self) -> Result<String, Error>
pub fn transcript_revision(&self) -> Result<String, Error>
Current transcript head revision. Rows written before transcript revisions derive their implicit head from the current message snapshot.
Sourcepub fn commit_transcript_rewrite(
&mut self,
selection: TranscriptRewriteSelection,
replacement: Vec<Message>,
reason: TranscriptRewriteReason,
actor: Option<String>,
expected_parent_revision: Option<String>,
) -> Result<TranscriptRewriteCommit, TranscriptEditError>
pub fn commit_transcript_rewrite( &mut self, selection: TranscriptRewriteSelection, replacement: Vec<Message>, reason: TranscriptRewriteReason, actor: Option<String>, expected_parent_revision: Option<String>, ) -> Result<TranscriptRewriteCommit, TranscriptEditError>
Commit a same-session transcript rewrite and advance the transcript head.
Store typed mob operator authority inside canonical build-state metadata.
Load typed mob operator authority from canonical build-state metadata.
Sourcepub fn fork_at(&self, index: usize) -> Self
pub fn fork_at(&self, index: usize) -> Self
Fork the session at a specific message index
Creates a new session with a subset of messages. The messages are copied (not shared) since the new session has a different prefix.
Sourcepub fn fork_replacing(
&self,
message_index: usize,
replacement: TranscriptReplacement,
) -> Result<Self, TranscriptEditError>
pub fn fork_replacing( &self, message_index: usize, replacement: TranscriptReplacement, ) -> Result<Self, TranscriptEditError>
Fork the session and replace the message at message_index.
The returned session contains the original prefix before
message_index, followed by the typed replacement. Later source
messages are intentionally omitted so follow-up work continues from the
edited branch rather than replaying stale descendants.