Skip to main content

Module session

codetether_agent

Module session 

Source
Expand description

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

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::index::Granularity;
pub use self::index::SummaryIndex;
pub use self::index::SummaryNode;
pub use self::index::SummaryRange;
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::SessionTaskStatus;
pub use self::tasks::TaskEvent;
pub use self::tasks::TaskLog;
pub use self::tasks::TaskState;
pub use self::types::DEFAULT_MAX_STEPS;
pub use self::types::ImageAttachment;
pub use self::types::Session;
pub use self::types::SessionMetadata;

Modules§

codex_import
context
Derive the per-step LLM context from an append-only chat history.
delegation
CADMAS-CTX delegation calibration (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.
index
Hierarchical summary index — Phase B step 14 scaffolding.
index_produce
RLM-backed summary production for [SummaryIndex::summary_for].
journal
Validated-writeback journal (ClawVM §3).
listing
oracle
Replay-oracle evaluation harness (ClawVM §3).
oracle_replay
Oracle replay evaluator (Step 22 — evaluation-only).
pages
Typed pages for chat-history entries (ClawVM §3).
relevance
Per-entry relevance metadata and CADMAS-CTX bucket projection.
step_limit
Step-limit outcome tracking for non-interactive resumable runs.
tasks
Session Task Log
types
Core data types for Session: the session struct itself, its persistent metadata, and the image attachment helper used by multimodal prompts.

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.
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
Progress tick from an in-flight RLM analysis loop.
RlmSubcallFallback
Emitted when a configured subcall model cannot be resolved and the router falls back to the root model.
RunCheckpoint
A structured checkpoint for a step-budget-exhausted codetether run.
SessionBus
Unified event bus for a single 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§

CheckpointReason
The reason a resumable run checkpoint was created.
FallbackStrategy
Which fallback path the compaction pipeline selected.
RlmOutcome
Why an RLM loop finished.
SessionEvent
Events emitted during session processing for real-time UI updates and durable telemetry.
TokenSource
Origin of a token accounting delta.

Traits§

DurableSink
A write-ahead sink for durable SessionEvents.

Functions§

auto_resume_prompt
list_all_sessions_for_directory