Skip to main content

Session

Struct Session 

Source
#[non_exhaustive]
pub struct Session {
Show 33 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 resumed_by_client: Option<ClientInfo>, pub spawned_by: Option<SessionSpawnedBy>, pub drive_holder: Option<ClientInfo>, pub worktree: Option<SessionWorktree>, pub current_limits: Option<SessionLimits>, pub running_elsewhere: Option<RunningElsewhere>, pub item_count: Option<u64>, pub log_bytes: Option<u64>,
}
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.

§resumed_by_client: Option<ClientInfo>

The handshake ClientInfo of the connection whose wire session/resume most recently loaded this session: stamped on the durable session.resumed marker, folded into the session index, and served from that column by every carrier; while the session is loaded, the stamp the loading resume wrote replaces the column on every carrier (the ack, session/read, session/list, session/listChanged), and after the next fold the column serves it. Additive-optional and provenance only; a resume with no admitting handshake (TUI, exec) stamps nothing, a warm attach to an already-loaded session writes no marker, and a half stamp serves nothing, so absence asserts nothing. createdByClient never follows a resume.

§spawned_by: Option<SessionSpawnedBy>

The session that opened this one, recorded once in this session’s creation record and served from the session index. Its parentSessionId is the exact spawner, unlike the containing session parentSessionId names above; project and thread are opaque labels the spawner may name beside it. Additive-optional and provenance only: never a visibility or authority gate. Absence asserts nothing — no recorded spawner, a later session of the spawned process, a row folded before the member existed, or a session the index has not folded yet.

§drive_holder: Option<ClientInfo>

The handshake ClientInfo of the connection that currently holds this session’s drive grant, served on session/read only, as name and version (the handshake’s display title is never served, the createdByClient rule). Additive-optional, loaded-only, live: present exactly when a live connection holds the grant and its handshake is known; absent on notLoaded rows, once the holder’s connection drops (its orphaned turn included), and for a holder with no handshake stamp. Provenance only: whether a client may drive is answered by session/resume / turn/start (sessionInUse), never by this member.

§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. workspaceTrusted is the trust the session runs with. 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.

§running_elsewhere: Option<RunningElsewhere>

That another live process on this machine runs this session, and which kind of process when the host can tell. Experimental (Session.runningElsewhere; stripped per-connection for unopted callers), on session/list rows and the session/listChanged frames built from the same row. No frame is pushed when only this member changes; a client sees the change on its next session/list or on a frame sent for another reason. Present exactly when the answering host does not hold the session loaded and another live process on this machine does (it holds the session’s writer lease, or a live local session registry record names the session), so only notLoaded rows carry it. Absence asserts only that the host saw no other holder when it built the row. Provenance only: whether a client may drive is answered by session/resume / turn/start (sessionInUse), never by this member.

§item_count: Option<u64>

The published head’s ordinal (kt-dvw5): the head reference’s own ordinal — the count of head slots in its sequence, including any reserved ones — as of the probe that served this row. A sizing hint for a first view/page, so the Console can size its page without folding the log. Additive-optional, present only on metadata reads (session/read with excludeItems), where the client has no items to count; full reads carry the items themselves and omit it. Absent when no head is published (unknown), never fabricated. May lag a live log: the head is a snapshot, and appends after its publication are not counted.

§log_bytes: Option<u64>

The durable log’s byte length at read time (kt-dvw5): the size hint paired with itemCount, so the Console can size its first page without folding the log. Additive-optional, present only on metadata reads (session/read with excludeItems); full reads omit it. Absent when the log’s length is not known (unknown), never fabricated. A live log grows after the read; the value is a snapshot.

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.