Skip to main content

Session

Struct Session 

Source
#[non_exhaustive]
pub struct Session {
Show 37 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 needs_input_reasons: Option<Vec<NeedsInputReason>>, 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 probe_degraded_reason: Option<ProbeDegradedReason>, 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 external_wait: Option<ExternalWaitView>, pub worktree: Option<SessionWorktree>, pub current_limits: Option<SessionLimits>, pub running_elsewhere: Option<RunningElsewhere>, pub quiescent: Option<bool>, 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 a turn is in flight (parked under needsInput included), and null otherwise.

Required-nullable. Every served Session carries the member: null when no turn is in flight or the session is not loaded, the turn id when one is. 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.

§needs_input_reasons: Option<Vec<NeedsInputReason>>

Why the session’s input is needed. Additive-optional, present only when non-empty; status is needsInput exactly when this set is non-empty (loaded sessions). Absence is a NON-assertion, on the attention discipline. Loaded sessions only: a notLoaded row omits it even while its durable pending set is non-empty. Experimental: stripped per-connection for unopted callers.

§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.

§probe_degraded_reason: Option<ProbeDegradedReason>

Why the workspace status probe produced no fresh reading — the index’s last derived value, like branch, so the TUI can show WHY status is unavailable instead of a generic unavailable. Additive-optional, omitted when the latest probed observation carries no reason or none exists. Open enum: a client treats an unknown-but-present reason and renders it, never rejecting the row.

§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 structured 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. Unlike the containing session parentSessionId names above, its parentSessionId is the exact spawner, except that any muse started in a later pane of the worker’s tmux session or Herdr workspace names the worker’s manager and carries the worker’s project/thread labels; 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.

§external_wait: Option<ExternalWaitView>

The live host-declared external wait for this session, served on session/read only. Additive-optional, loaded-only, live: present exactly while a declaration is live for the loaded session; absent on notLoaded rows, once the declaration is cleared, once the next user input clears it, and after a restart or resume, which lose it. Presence is the declaration — a client must never infer one from any other 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 — each axis the session chose clamps its durable stored choice (the clamp input) to the live ceiling, and an axis it never chose reads the daemon default: untrusted unless the daemon serves trusted by default, and the daemon’s own posture on the sandbox axes, except that a resume over a sandbox-off posture can keep a recorded sandbox on, and a session/fork or session/sideChat child starts with its parent’s recorded shell, write and sandbox limits and its parent’s chosen trust, clamped to the live ceiling. A sandbox kept on this way over a sandbox-off posture runs its recorded network, or restricted when none was recorded, while a tracked change is open. These are the limits 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.

§quiescent: Option<bool>

Whether the answering host holds no live work for this loaded session: the held predicate the host’s idle unload and upgrade drain use, over the pending answer attention reads. true when it finds no run in flight or finishing its post-run work, no owned background task or live background process, no background completion waiting to wake the session, no session-name or goal-recovery work, and no pending approval, user-input or admission request; false while any is held or a read cannot prove it absent. Experimental (Session.quiescent; stripped per-connection for unopted callers) and loaded-only: carried by session/read, session/list rows, the session/resume result and the session/listChanged frames built from the same row. A run or a pending request starting pushes a frame carrying false; other held work (session-name maintenance, a leave in progress) shows on the next read. A session served false is rechecked about once a second and its frame is pushed once it reads true. Absent on notLoaded rows, on a host whose session_quiescent_witness gate is off, and for a session with no live pending-request source: absence asserts nothing.

§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.