#[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
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.session_id: StringThe session identity.
path: StringAbsolute 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: SessionStatusLoad 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: StringRFC3339. For a fork this is the fork session id’s UUIDv7 mint instant.
updated_at: StringRFC3339; 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: u64Completed-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.