Module session 

Session Management

A Session tracks the conversation history and execution state for a single agent interaction. It is the primary abstraction used by the CLI, TUI, HTTP server, and A2A worker to drive the agentic loop: send a user message, let the model call tools until it converges, and return the final answer.

Quick Start

use codetether_agent::session::Session;

let mut session = Session::new().await.unwrap();
let result = session.prompt("List the files in the current directory").await.unwrap();
println!("Assistant: {}", result.text);
println!("Session ID: {}", result.session_id);

Architecture

Sessions are stored as JSON files in the platform data directory (~/.local/share/codetether/sessions on Linux). Each session has a UUID, an ordered list of Messages, a record of all ToolUse events, aggregated token Usage, and a SessionMetadata block.

Module Layout

The Session type is implemented across several single-responsibility submodules and exposed here as a single facade:

• [types] — Session, SessionMetadata, ImageAttachment.
• [events] — SessionResult, SessionEvent.
• [lifecycle] — constructor, agent/provenance, message append.
• [persistence] — save / load / delete / directory lookup.
• [title] — title generation and context-change hook.
• [prompt_api] — public prompt entry points.
• helper — the agentic loop implementation (non-public details).

Re-exports

pub use self::codex_import::import_codex_session_by_id;

pub use self::codex_import::import_codex_sessions_for_directory;

pub use self::codex_import::load_or_import_session;

Modules

codex_import

helper

Internal helpers used by Session and its prompt loops.

Structs

CompactionFailure

Emitted when every fallback strategy failed to fit under budget.

CompactionOutcome

Emitted when a compaction pass finishes successfully.

CompactionStart

Emitted when a compaction pass begins.

ContextTruncation

Emitted when the terminal truncation fallback fires.

ImageAttachment

An image attachment to include with a user message (e.g. pasted from the clipboard in the TUI).

NoopSink

A DurableSink that drops every event. Useful as a default when the caller has no persistence requirement (e.g. in unit tests or one-shot CLI invocations).

RlmCompletion

Terminal record for a single RLM invocation.

RlmProgressEvent

One progress tick emitted by an in-flight RLM analysis loop.

RlmSubcallFallback

Emitted when a configured subcall_model could not be resolved, forcing the router to fall back to the root model.

Session

A conversation session.

SessionBus

Unified event bus for a single session.

SessionMetadata

Persistent, user-facing configuration for a Session.

SessionResult

Result returned from Session::prompt and friends.

SessionSummary

Summary of a session for listing

TokenDelta

A single token-consumption delta observed during session processing.

TokenEstimate

Pre-flight estimate of the next request’s token footprint.

Enums

FallbackStrategy

Which fallback path the compaction pipeline selected.

RlmOutcome

Why a Recursive Language Model loop finished.

SessionEvent

Events emitted during session processing for real-time UI updates and durable telemetry.

TokenSource

Origin of a token accounting delta.

Constants

DEFAULT_MAX_STEPS

Default maximum agentic loop iterations when Session::max_steps is None.

Traits

DurableSink

A write-ahead sink for durable SessionEvents.

Functions

list_all_sessions_for_directory

list_sessions

List all sessions