Struct Session 

pub struct Session {

    pub input: String,
    pub input_images: Vec<ImageAttachment>,
    pub input_text_files: Vec<TextFileAttachment>,
    pub output_lines: Vec<String>,
    pub workflow_tx: UnboundedSender<TuiMessage>,
    pub workflow_state: WorkflowState,
    pub config_toml: Option<String>,
    pub secrets: Option<HashMap<String, String>>,
    pub build_info: Option<BuildInfo>,
    pub resume_info: Option<ResumeInfo>,
    pub backup_resume_info: Option<ResumeInfo>,
    pub todo_lines: Vec<String>,
    pub cancel_token: CancellationToken,
    pub pending_command: Option<String>,
    pub handoff_pending: bool,
    pub pending_tool_lines: Vec<(String, usize, Option<String>)>,
    pub current_context_tokens: usize,
    pub auto_handoff: AutoHandoffConfig,
    pub mcp_servers: Vec<McpServerInfo>,
    pub should_quit: bool,
    pub auto_scroll: bool,
    pub agent_name: String,
    pub token_store: Option<Arc<dyn TokenStore>>,
    pub mcp_loader: Option<()>,
    pub project_id: Option<String>,
    pub project_name: Option<String>,
    pub session_id: Option<String>,
    pub session_name: Option<String>,
    pub home_dir: Option<PathBuf>,
    pub workflow_permit: Option<OwnedSemaphorePermit>,
    pub identity: Option<String>,
    pub model: Option<String>,
    pub rotating_from_handoff: bool,
    pub briefing_born: bool,
    pub handoff_count: u32,
    pub compaction_status: SharedCompactionStatus,
}

Holds all state that is independent of the presentation layer (TUI, API, Web). Frontend crates compose this struct and add their own UI-specific fields.

Fields

input: String

Input buffer for user commands

input_images: Vec<ImageAttachment>

Pre-loaded image attachments (multimodal) for the next command. Consumed by execute_command and attached to the initial user turn; callers (API/web) fill this before invoking execute_command.

input_text_files: Vec<TextFileAttachment>

Pre-loaded text/markdown file attachments for the next command. Same lifecycle as input_images: callers fill before execute_command; consumed exactly once. Composed into the task text as fenced synthetic blocks.

output_lines: Vec<String>

Output log lines

workflow_tx: UnboundedSender<TuiMessage>

Sender for messages from async workflows (clone and pass to workflow runners)

workflow_state: WorkflowState

Current workflow lifecycle state

config_toml: Option<String>

Configuration TOML for ABK workflows

secrets: Option<HashMap<String, String>>

Secrets for ABK workflows

build_info: Option<BuildInfo>

Build info for ABK workflows

resume_info: Option<ResumeInfo>

Resume info from the last completed task for session continuity

backup_resume_info: Option<ResumeInfo>

Saved resume_info before execute_command consumes it; restored if task is cancelled before producing a real checkpoint (mistake-ENTER recovery).

todo_lines: Vec<String>

Latest todo list from LLM todowrite tool

cancel_token: CancellationToken

Cancellation token for aborting the current workflow

pending_command: Option<String>

Command buffered by user during cancellation wind-down.

handoff_pending: bool

Whether a session handoff (Ctrl+H) should fire once the current workflow cancels.

pending_tool_lines: Vec<(String, usize, Option<String>)>

In-flight spinner entries: (tool_name, output_lines_index, hint).

current_context_tokens: usize

Current context token count (updated from ApiCallStarted events).

auto_handoff: AutoHandoffConfig

Auto-handoff configuration parsed from [tui.auto_handoff].

mcp_servers: Vec<McpServerInfo>

MCP server statuses received from agent init

should_quit: bool

Whether the session should quit

auto_scroll: bool

Whether auto-scroll is enabled (follows new output)

agent_name: String

Agent name for checkpoint/token paths (replaces ABK_AGENT_NAME env var). Defaults to “trustee”. Set from config at startup.

token_store: Option<Arc<dyn TokenStore>>

Per-session token store (None = FileTokenStore fallback). When set, MCP credential flows use this instead of file-based storage.

mcp_loader: Option<()>

project_id: Option<String>

Storage partition key (replaces path hash). None = hash(working_dir)

project_name: Option<String>

Human-readable project name. None = directory name

session_id: Option<String>

Storage directory name (replaces timestamp slug). None = auto-generate

session_name: Option<String>

Human-readable session name. None = no description

home_dir: Option<PathBuf>

Per-user home directory for checkpoint storage. None = default ~/.{agent_name}/ Set to ~/.trustee/users/{user_hash}/ for per-user isolation in web mode.

workflow_permit: Option<OwnedSemaphorePermit>

Concurrency permit — held while a workflow is running. When the workflow completes (state → Idle), this is dropped, releasing the permit back to the global semaphore. None when no workflow is running or when concurrency limiting is disabled.

identity: Option<String>

Optional agent identity content (e.g. fetched from Fame). When set, prepended to lifecycle.system_template in the config clone inside execute_command() and trigger_handoff(). None = use the config’s default system template.

model: Option<String>

Optional model override for the next command. When set, [llm.providers.{model}] from the config TOML is injected into [llm.provider] before creating the agent, switching the LLM for that command. Consumed per-command (cleared after injection). None = use the default [llm.provider].

rotating_from_handoff: bool

Set to true immediately before the post-handoff briefing execute, so execute_command treats that run as a rotation rather than a fresh session: it derives a new chain identity but does NOT clear the visible transcript (Bug 2). Cleared once the rotation is handled.

briefing_born: bool

True while the current chain identity was born from a handoff briefing and no user command has run in it yet (Bug 4). While true, handoff is blocked entirely (manual + auto) to prevent briefing-of-briefing loops. Cleared on the first user-initiated command.

handoff_count: u32

Monotonic count of handoff rotations this session has performed. Surfaced in live-session listings so the UI can show lineage (Bug 5: “name rotated silently” → “name · ↻2”).

compaction_status: SharedCompactionStatus

Shared compaction-status handle (abk 0.21.4).

The session owns the handle and threads a clone through the run’s RunContext; abk’s compaction loop stamps in_progress/started_at while a summarization run is in flight and records the durable last trace on completion. trustee-api reads it in the live-session payload so consoles can show “compacting…” state that survives a refresh (the /compact command never enters the transcript — it is intercepted before becoming a task message).

Implementations

impl Session

pub fn new() -> (Self, UnboundedReceiver<TuiMessage>)

Create a new Session with default state and a fresh message channel.

Returns (Session, Receiver) so the caller can own the receiver without locking the session (prevents deadlock in async drain loops).

pub fn parse_auto_handoff_config(&mut self)

Parse auto-handoff configuration from the stored config TOML.

pub fn handle_workflow_message(&mut self, msg: TuiMessage)

Handle messages from async workflows.

This processes all workflow lifecycle events, output updates, and state transitions. Returns true if the caller should check for pending commands/handoffs after.

pub fn execute_command(&mut self)

Execute the current command in the input buffer.

Spawns an async ABK workflow task, clears the input buffer, and sets workflow_state to Running.

pub fn request_handoff(&mut self, hint: String)

Request a session handoff through the safe state-machine entry point.

Mirrors the TUI Ctrl+H behavior:

• Idle → trigger the handoff immediately
• Running → cancel the workflow, fire handoff once it stops
• Cancelling → queue handoff for when it stops

This prevents any caller (web button, API, future MCP tool) from spawning a briefing task concurrently with a running workflow (Bugs 1/2/5).

pub fn trigger_handoff(&mut self, hint: String)

Trigger a session handoff.

Runs a single LLM call using the current session’s resume_info to generate a briefing. On completion, sends TuiMessage::HandoffReady(briefing).

This is the internal Idle-only entry point. Callers that may be invoked while a workflow is running should use Session::request_handoff.

Trait Implementations

impl Default for Session

fn default() -> Self

Returns the “default value” for a type.