Skip to main content

Session

Struct Session 

Source
#[non_exhaustive]
pub struct Session {
Show 27 fields pub session_id: String, pub path: String, pub status: SessionStatus, pub active_turn_id: Option<String>, pub created_at: String, pub updated_at: String, pub workspace_root: Option<String>, pub provider_id: Option<String>, pub model_id: Option<String>, pub approval_mode: Option<EffectiveApprovalModeState>, pub permission_state: Option<EffectivePermissionState>, pub attention: Option<Vec<AttentionFlag>>, pub last_activity_at: Option<String>, pub turn_count: u64, pub forked_from: Option<ForkProvenance>, pub side_from: Option<SideProvenance>, pub name: Option<String>, pub name_origin: Option<SessionNameOrigin>, pub generated_name: Option<String>, pub title: Option<String>, pub first_user_prompt: Option<String>, pub branch: Option<String>, pub kind: Option<SessionKind>, pub parent_session_id: Option<String>, pub created_by_client: Option<ClientInfo>, pub worktree: Option<SessionWorktree>, pub current_limits: Option<SessionLimits>,
}
Expand description

The session object every lifecycle method returns or lists.

Additive-optional evolution applies: clients must ignore unknown fields.

Fields (Non-exhaustive)§

This struct is marked as non-exhaustive
Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.
§session_id: String

The session identity.

§path: String

Absolute path of the session’s durable log; non-nullable. Under the ephemeral session profile it is the empty string, meaning “no durable log exists” — the one value a client must not hand to a filesystem call.

§status: SessionStatus

Load state as this host knows it; session/list reports notLoaded for sessions loaded by other hosts.

§active_turn_id: Option<String>

The turnId of the current foreground turn when status is running, and null when the session is idle.

Required-nullable. Every served Session carries the member: null when the session is idle or not loaded, the turn id when it is running. An optional-absent shape would publish it as plain string and reject every idle Session frame the host sends.

§created_at: String

RFC3339. For a fork this is the fork session id’s UUIDv7 mint instant.

§updated_at: String

RFC3339; never precedes createdAt.

§workspace_root: Option<String>

The winning metadata fold’s workspace root; null when that record omits it — absent is never fabricated.

§provider_id: Option<String>

The winning metadata fold’s provider; null when that record omits it.

§model_id: Option<String>

The winning metadata fold’s model; null when that record omits it.

§approval_mode: Option<EffectiveApprovalModeState>

The folded effective approval mode. Additive-optional: a Session object that omits it means the host has not folded a mode, which is why the index-derived session/list entry may legitimately omit it.

§permission_state: Option<EffectivePermissionState>

The folded effective permission state. Additive-optional: a "notLoaded" row omits it (no live evidence, matching the attention precedent) and an older host omits it everywhere; absent is unknown, never active. approvalMode stays the effective-mode answer; this never restates it.

§attention: Option<Vec<AttentionFlag>>

Attention flags. Additive-optional, present only when at least one flag is set; absence is a NON-assertion (nothing pending, or the loaded session’s pending source declined to answer). Loaded sessions only: a notLoaded row omits it even while its durable pending set is non-empty.

§last_activity_at: Option<String>

Content-activity recency, RFC3339. Additive-optional: omitted when no content record exists. Never advanced by lifecycle bookkeeping (the resume marker, re-stamps) or a fork’s copied seed-replay records, and never precedes createdAt.

§turn_count: u64

Completed-turn count from the session view fold.

§forked_from: Option<ForkProvenance>

null for root sessions; fork provenance otherwise.

§side_from: Option<SideProvenance>

null for root sessions and forks; side provenance otherwise. A session carries at most one of forkedFrom and sideFrom.

§name: Option<String>

The durable allocated session name. Additive-optional: present when the serving path holds an allocated name, omitted otherwise — absent is never fabricated. Authoritative and renameable via session/rename.

§name_origin: Option<SessionNameOrigin>

How the served name was set. Additive-optional, fold-only: the snapshot fold (session/read, the resume/start/fork-ack snapshot) derives and carries it from the log; session/list rows never carry it. Absent — and any value the client does not recognize — reads as unknown, never fabricated.

§generated_name: Option<String>

The served generated short title. Additive-optional, fold-only: the snapshot fold derives the latest retained generated pair’s short title from the log; session/list rows never carry it. Omitted when no pair was ever published — absent reads as unpublished, never fabricated, never inferred from the name text. name stays the canonical name it always was.

§title: Option<String>

Derived display title: a heuristic that may evolve — its carriage, not its derivation, is the contract. Additive-optional, omitted when underivable.

§first_user_prompt: Option<String>

Derived first-user-prompt preview. Additive-optional, omitted when underivable.

§branch: Option<String>

Derived workspace branch — the index’s last derived value; the live-change signal stays session/branchChanged. Additive-optional, omitted when underivable.

§kind: Option<SessionKind>

What kind of session this is. Open enum, v1 values "root" and "subagent"; a client treats an unknown value as an unknown-but-present kind and renders it, never rejecting the row. Additive-optional: absence asserts nothing — the host could not determine the home shape, or the value is not yet available to serve.

§parent_session_id: Option<String>

The containing session’s id when kind is "subagent" — the id of the TOP-LEVEL session whose home holds this child, which is not necessarily the session that spawned it: native-child homes are physical siblings under the outer session’s subagent/ directory, so a subagent spawned by another subagent resolves to the outer session, not to its spawner. A client building a tree from this field gets one level, not a chain. Flat rather than nested: there is exactly one fact to carry, unlike forkedFrom’s four-field ForkProvenance. Additive-optional; a root carries none.

§created_by_client: Option<ClientInfo>

The handshake ClientInfo recorded when the session was opened, echoed verbatim — provenance, never an interpretation, and never a visibility gate. Additive-optional; absence has four indistinguishable causes: an in-process open; an earlier record; a half stamp where only one of name/version was recorded and ClientInfo requires both; and a session with no admitting handshake of its own — a fork child or a subagent — which never carries a stamp to begin with.

§worktree: Option<SessionWorktree>

The worktree this session runs in — path and origin only (the branch stays in branch). Experimental (Session.worktree; stripped per-connection for unopted callers). Omitted when the session runs in no worktree.

§current_limits: Option<SessionLimits>

This session’s effective limits: the clamp output — the sandbox axes read the live ceiling, the trust axis clamps the session’s durable stored choice (the clamp input) to it. Until a tracked change lands, workspaceTrusted reports the recorded choice. Experimental, same-user socket only (Session.currentLimits; stripped per-connection for unopted callers). Loaded sessions only (notLoaded rows and hosts with no limits regime omit it) — absent is never fabricated.

Trait Implementations§

Source§

impl Clone for Session

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Session

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

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

Deserialize this value from the given Serde deserializer. Read more
Source§

impl Eq for Session

Source§

impl PartialEq for Session

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl Serialize for Session

Source§

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

Serialize this value into the given Serde serializer. Read more
Source§

impl StructuralPartialEq for Session

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.