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.
• context — DerivedContext + derive_context: produce the per-step LLM context from the append-only chat history without mutating Session::messages. See the Phase A plan.
• 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;

pub use self::context::DerivedContext;

pub use self::context::derive_context;

pub use self::context::derive_with_policy;

pub use self::context::effective_policy;

pub use self::delegation::BetaPosterior;

pub use self::delegation::DelegationConfig;

pub use self::delegation::DelegationState;

pub use self::derive_policy::DerivePolicy;

pub use self::eval::PolicyRunResult;

pub use self::eval::pareto_frontier;

pub use self::eval::reuse_rate;

pub use self::faults::Fault;

pub use self::history::History;

pub use self::history_sink::HistorySinkConfig;

pub use self::history_sink::PointerHandle;

pub use self::journal::JournalEntry;

pub use self::journal::Op;

pub use self::journal::RejectReason;

pub use self::journal::TxnId;

pub use self::journal::WritebackJournal;

pub use self::listing::SessionSummary;

pub use self::listing::list_sessions;

pub use self::oracle::OracleReport;

pub use self::oracle::replay_oracle;

pub use self::pages::PageKind;

pub use self::pages::ResidencyLevel;

pub use self::relevance::Bucket;

pub use self::relevance::Dependency;

pub use self::relevance::Difficulty;

pub use self::relevance::RelevanceMeta;

pub use self::relevance::ToolUse;

pub use self::relevance::bucket_for_messages;

pub use self::tasks::TaskEvent;

pub use self::tasks::TaskLog;

pub use self::tasks::TaskState;

pub use self::tasks::TaskStatus;

Modules

codex_import

context

Derive the per-step LLM context from an append-only chat history.

delegation

CADMAS-CTX delegation posteriors (arXiv:2604.17950).

delegation_skills

Canonical skill-name constants for CADMAS-CTX delegation hooks.

derive_policy

Selectable derivation policies for derive_with_policy.

eval

Pareto evaluation harness for [DerivePolicy].

faults

Observable faults with typed reason codes (ClawVM §3).

helper

Internal helpers used by Session and its prompt loops.

history

Append-only view of a session’s chat history.

history_sink

Durable MinIO/S3 sink for pure chat history.

journal

Validated-writeback journal (ClawVM §3).

listing

oracle

Replay-oracle evaluation harness (ClawVM §3).

pages

Typed pages for chat-history entries (ClawVM §3).

relevance

Per-entry relevance metadata and CADMAS-CTX bucket projection.

tasks

Session Task Log

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.

TailLoad

Result of a bounded session load.

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