Struct Session 

pub struct Session {

    pub id: String,
    pub title: String,
    pub pinned: bool,
    pub title_version: u64,
    pub title_generated: bool,
    pub metadata_version: u64,
    pub kind: SessionKind,
    pub authority_identity: SessionAuthorityIdentity,
    pub supervisor_management: Option<SupervisorManagementState>,
    pub parent_session_id: Option<String>,
    pub root_session_id: String,
    pub spawn_depth: u32,
    pub messages: Vec<Message>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub task_list: Option<TaskList>,
    pub pending_question: Option<PendingQuestion>,
    pub model: String,
    pub model_ref: Option<ProviderModelRef>,
    pub reasoning_effort: Option<ReasoningEffort>,
    pub metadata: HashMap<String, String>,
    pub token_budget: Option<TokenBudget>,
    pub resolved_token_budget: Option<(String, TokenBudget)>,
    pub token_usage: Option<TokenBudgetUsage>,
    pub conversation_summary: Option<ConversationSummary>,
    pub prompt_snapshot: Option<PromptSnapshot>,
    pub compression_events: Vec<CompressionEvent>,
    pub model_context_state: Option<ModelContextState>,
    pub provider_transcript: ProviderTranscriptState,
    pub compression_instructions: Option<String>,
    pub agent_runtime_state: Option<AgentRuntimeState>,
    pub runtime_metadata: Option<SessionRuntimeMetadata>,
    pub force_manual_compression: Option<String>,
    pub workspace: Option<String>,
}

A complete conversation session with state management.

Fields

id: String

title: String

pinned: bool

title_version: u64

title_generated: bool

Whether the initial title lifecycle has been finalized. New root sessions start pending (false); generated, fallback, and explicit manual titles finalize it (true). Legacy sessions default to true so an upgrade never overwrites an existing user-authored title.

metadata_version: u64

Authoritative UI metadata revision. Bumped by every authoritative metadata write (title / pinned / future replayable metadata fields). Runtime / non-authoritative paths must not bump this; they read it to detect when their session struct holds stale UI metadata.

kind: SessionKind

authority_identity: SessionAuthorityIdentity

Trusted identity; raw metadata and ordinary persistence cannot assign it.

supervisor_management: Option<SupervisorManagementState>

Trusted host-managed scope and links; ordinary constructors never inherit it.

parent_session_id: Option<String>

root_session_id: String

spawn_depth: u32

messages: Vec<Message>

created_at: DateTime<Utc>

updated_at: DateTime<Utc>

task_list: Option<TaskList>

pending_question: Option<PendingQuestion>

model: String

model_ref: Option<ProviderModelRef>

reasoning_effort: Option<ReasoningEffort>

metadata: HashMap<String, String>

token_budget: Option<TokenBudget>

resolved_token_budget: Option<(String, TokenBudget)>

Runtime snapshot of the model-limit-derived budget for downstream readers in the current round, keyed by model. It is never persisted and never short-circuits the next round’s resolution, so live model_limits.json edits and provider-metadata refreshes take effect without reloading the session. token_budget above remains the persisted genuine/child override that takes priority. (#180, #763)

token_usage: Option<TokenBudgetUsage>

conversation_summary: Option<ConversationSummary>

prompt_snapshot: Option<PromptSnapshot>

compression_events: Vec<CompressionEvent>

model_context_state: Option<ModelContextState>

Durable, provider-neutral host-context timeline. Synthetic ledger events are projected only into model requests and never exposed through messages or the existing session API/UI transcript.

provider_transcript: ProviderTranscriptState

Durable provider-native discovery history. This is separate from the user-visible messages lane and is replayed only through a matching provider family/protocol adapter.

compression_instructions: Option<String>

Custom instructions for conversation summarization at the session level. Overrides config-level compression_instructions when set.

agent_runtime_state: Option<AgentRuntimeState>

runtime_metadata: Option<SessionRuntimeMetadata>

Typed view over the well-known runtime metadata keys previously smuggled through metadata. Accessed via the symmetric accessor layer (runtime_metadata_access) which dual-writes the legacy metadata strings and falls back to them on read. Additive/optional: old persisted sessions without this field load cleanly.

force_manual_compression: Option<String>

Runtime-only flag: when set, the next mid-turn compression check should force compression regardless of threshold. Set by compact_context tool.

workspace: Option<String>

Workspace directory for file operations in this session. For child sessions, this is set from the workspace field in CreateChildInput.

Implementations

impl Session

pub fn activate_provider_transcript_route( &mut self, family: ProviderFamily, protocol: ProviderProtocol, provider_boundary_sha256: &str, ) -> Result<bool, ProviderTranscriptError>

pub fn deactivate_provider_transcript_route(&mut self) -> bool

pub fn append_provider_transcript_group( &mut self, anchor_message_id: impl Into<String>, id_hint: Option<&str>, items: Vec<ProviderTranscriptItem>, ) -> Result<String, ProviderTranscriptError>

pub fn prune_provider_transcript(&mut self) -> usize

pub fn invalidate_provider_transcript( &mut self, reason: ProviderTranscriptResetReason, )

pub fn merge_provider_transcript_from_durable( &mut self, durable: &Session, ) -> usize

impl Session

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

pub fn set_subagent_type(&mut self, value: impl Into<String>)

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

pub fn set_last_run_status(&mut self, value: impl Into<String>)

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

pub fn set_last_run_error(&mut self, value: impl Into<String>)

pub fn clear_last_run_error(&mut self)

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

pub fn set_provider_name(&mut self, value: impl Into<String>)

pub fn pending_injected_messages(&self) -> Option<Vec<Value>>

Read the pending injected messages, decoding the legacy JSON-string form defensively. Malformed legacy JSON yields None (never a panic).

pub fn set_pending_injected_messages(&mut self, messages: Vec<Value>)

Set pending injected messages on both planes. The legacy mirror stores the JSON-encoded string form to preserve byte-for-byte compatibility.

pub fn has_pending_injected_messages(&self) -> bool

True when there are queued injected messages on either plane.

pub fn take_pending_injected_messages(&mut self) -> Option<Vec<Value>>

Take and clear pending injected messages from both planes.

pub fn clear_pending_injected_messages(&mut self)

pub fn session_inbox_admission(&self) -> Option<&SessionInboxAdmissionState>

pub fn session_inbox_admission_mut(&mut self) -> &mut SessionInboxAdmissionState

pub fn selected_skill_ids(&self) -> Option<Vec<String>>

Read selected skill ids. The typed field is preferred; the legacy fallback parses the stored JSON-array string defensively (malformed → None).

pub fn set_selected_skill_ids(&mut self, ids: Vec<String>)

Set selected skill ids on both planes. The legacy mirror stores the JSON-array string form.

pub fn clear_selected_skill_ids(&mut self)

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

Read the skill mode. Resolution order: typed field, then legacy skill_mode key, then the historical mode key. When both legacy keys are present and disagree, a warning is logged and skill_mode wins.

pub fn set_skill_mode(&mut self, value: impl Into<String>)

Set the skill mode. Writes the typed field and the canonical skill_mode legacy key (the legacy mode key is never written).

pub fn clear_skill_mode(&mut self)

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

pub fn set_reasoning_effort_meta(&mut self, value: impl Into<String>)

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

pub fn set_enhance_prompt(&mut self, value: impl Into<String>)

pub fn clear_enhance_prompt(&mut self)

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

pub fn set_task_list_version_meta(&mut self, value: impl Into<String>)

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

pub fn set_todo_list_version_meta(&mut self, value: impl Into<String>)

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

pub fn set_workspace_path_meta(&mut self, value: impl Into<String>)

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

Read the stable Project identity, preferring typed runtime metadata and falling back to the legacy metadata string during migration.

pub fn set_project_id_meta(&mut self, value: impl Into<String>)

Persist Project identity on both planes while legacy raw-map readers remain in the tree.

pub fn clear_project_id_meta(&mut self)

impl Session

pub fn clear_stale_root_token_budget(&mut self)

Load-boundary migration: a persisted Root session’s token_budget can only be a stale pre-#180 resolved-budget cache — genuine budgets flow through config.token_budget, and only a Child persists an assigned sub-budget. Clear it so resolve_token_budget re-resolves from the current model_limits.json instead of short-circuiting on the stale value forever.

MUST be called only on freshly disk-loaded sessions — never inside resolve_token_budget, which can’t tell a stale disk cache from a legitimate in-memory budget injection (tests, child sub-budgets). (#230)

pub fn effective_token_budget(&self) -> Option<&TokenBudget>

The effective token budget: a genuine/child override (token_budget) if set, otherwise the current round’s resolved-budget snapshot (resolved_token_budget). Both are None until the first resolution. Downstream readers should use this rather than token_budget directly so they observe the engine-resolved budget without persisting it. Note the snapshot is returned regardless of which model it was resolved for; that is safe because resolve_token_budget runs at round start (re-keying to the current model) before any reader — don’t call this expecting model-freshness without a preceding same-round resolve. (#180)

pub fn new(id: impl Into<String>, model: impl Into<String>) -> Session

pub fn new_child( id: impl Into<String>, root_session_id: impl Into<String>, model: impl Into<String>, title: impl Into<String>, ) -> Session

Create a child session directly under root_session_id — a flat, depth-1 child of the root. Use Session::new_child_of when the parent may itself be a child (nested sub-agents).

pub fn new_child_of( id: impl Into<String>, parent: &Session, model: impl Into<String>, title: impl Into<String>, ) -> Session

Create a child session whose parent is parent, supporting arbitrary nesting depth. The child inherits the parent’s tree root and sits one level deeper, so completion/SSE bookkeeping (which keys on root_session_id) sees the whole tree regardless of depth.

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

pub fn compact_oversized_tool_messages(&mut self) -> usize

pub fn clear_derived_context_state(&mut self)

Clear all ephemeral/derived state that should not persist across turns.

Resets token usage, compression state, previous response metadata, and message compression flags. Typically called before a truncation or when refreshing session state for a new execution.

pub fn reset_model_context_epoch(&mut self, reason: ModelContextResetReason)

Mark a deliberate model-history rewrite. The next engine reconciliation coalesces current host state into this new epoch before dispatch.

pub fn reset_provider_transcript_for_model_context( &mut self, reason: ModelContextResetReason, )

Apply a model-context boundary to the provider-native replay lane. Engine reconciliation uses this when it discovers an implicit boundary; callers that already declared a full model-context reset use Self::reset_model_context_epoch so both lanes move atomically.

pub fn set_task_list(&mut self, task_list: TaskList)

pub fn update_task_item( &mut self, item_id: &str, status: TaskItemStatus, notes: Option<&str>, criteria_met: Option<&[String]>, ) -> Result<String, String>

pub fn format_task_list_for_prompt(&self) -> String

pub fn set_pending_question( &mut self, tool_call_id: String, tool_name: String, question: String, options: Vec<String>, allow_custom: bool, )

pub fn set_pending_question_with_source( &mut self, tool_call_id: String, tool_name: String, question: String, options: Vec<String>, allow_custom: bool, source: PendingQuestionSource, )

pub fn clear_pending_question(&mut self)

pub fn has_pending_question(&self) -> bool

Trait Implementations

impl Clone for Session

fn clone(&self) -> Session

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Session

fn deserialize<__D>( __deserializer: __D, ) -> Result<Session, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Session

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.