Struct Session 

pub struct Session {
    pub session_id: String,
    pub agent_id: String,
    pub created_at: DateTime<Utc>,
    pub last_active_at: DateTime<Utc>,
    pub formation: SessionFormation,
    pub parent_spawn_ref: Option<SpawnRef>,
    pub scope: SessionScope,
    pub loops: Vec<LoopRecord>,
}

A named container grouping all LoopRecords for one agent session.

Loop tree structure

The tree is implicit via parent_loop_id / children_loop_ids links:

• Root loops — parent_loop_id is None (or points to a loop in a different session for sub-agent roots).
• Continuation chains — parent_loop_id → loop_id within the same session.
• Parallel branches — siblings sharing the same parent_loop_id, each with parallel_group set.
• Sub-agent children — in child_loop_refs on the parent loop (cross-session, not in loops vec).

Cross-session sub-agent tracking

When this session was itself spawned as a sub-agent, [parent_spawn_ref] points back to the parent session and loop that triggered it. This is the inverse of LoopRecord::child_loop_refs in the parent session, and together they form a complete bidirectional cross-session spawn graph.

Fields

session_id: String

Stable identifier for this session — matches AgentStart.session_id.

agent_id: String

The agent_id from the first AgentStart seen for this session.

created_at: DateTime<Utc>

Timestamp of the first AgentStart event seen for this session.

last_active_at: DateTime<Utc>

Timestamp of the most recent AgentStart event seen for this session.

Updated each time a new loop opens (on AgentStart), so it reflects when the last loop started, not when it last had activity.

formation: SessionFormation

Why this session was created.

parent_spawn_ref: Option<SpawnRef>

Set when this session was spawned as a sub-agent by a loop in a different session. Populated by [SessionRecorder] when a new session’s first AgentStart carries a parent_loop_id that belongs to a different session_id.

scope: SessionScope

Session scope — ephemeral (in-memory only) or persistent (written to store) (G7).

loops: Vec<LoopRecord>

All completed and in-progress LoopRecords, ordered by LoopRecord::started_at.

Implementations

impl Session

pub fn root_loops(&self) -> impl Iterator<Item = &LoopRecord>

Return root loops — those whose parent_loop_id is None or whose parent belongs to a different session.

pub fn children_of<'a>( &'a self, loop_id: &str, ) -> impl Iterator<Item = &'a LoopRecord>

Return all direct same-session children of loop_id.

pub fn parallel_siblings<'a>( &'a self, loop_id: &str, ) -> impl Iterator<Item = &'a LoopRecord>

Return all loops in the same parallel group as loop_id.

pub fn get_loop(&self, loop_id: &str) -> Option<&LoopRecord>

Look up a loop by its loop_id.

pub fn get_loop_mut(&mut self, loop_id: &str) -> Option<&mut LoopRecord>

Mutable look up a loop by its loop_id.

pub fn loop_chain_to(&self, target_loop_id: &str) -> Vec<String>

Build the linear chain of loops from root to target_loop_id by walking parent_loop_id links backward. Returns loop IDs in chronological order (root first).

This naturally handles parallel branches (only the selected path) and reruns (only the active ancestor chain).

pub fn total_usage(&self) -> Usage

Cumulative token usage across all loops in this session.

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

Formats the value using the given formatter.

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

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::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::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.