codetether_agent/session/
mod.rs

1//! # Session Management
2//!
3//! A [`Session`] tracks the conversation history and execution state for a
4//! single agent interaction. It is the primary abstraction used by the CLI,
5//! TUI, HTTP server, and A2A worker to drive the agentic loop: send a user
6//! message, let the model call tools until it converges, and return the
7//! final answer.
8//!
9//! ## Quick Start
10//!
11//! ```rust,no_run
12//! # tokio::runtime::Runtime::new().unwrap().block_on(async {
13//! use codetether_agent::session::Session;
14//!
15//! let mut session = Session::new().await.unwrap();
16//! let result = session.prompt("List the files in the current directory").await.unwrap();
17//! println!("Assistant: {}", result.text);
18//! println!("Session ID: {}", result.session_id);
19//! # });
20//! ```
21//!
22//! ## Architecture
23//!
24//! Sessions are stored as JSON files in the platform data directory
25//! (`~/.local/share/codetether/sessions` on Linux). Each session has a UUID,
26//! an ordered list of [`Message`](crate::provider::Message)s, a record of
27//! all [`ToolUse`](crate::agent::ToolUse) events, aggregated token
28//! [`Usage`](crate::provider::Usage), and a [`SessionMetadata`] block.
29//!
30//! ## Module Layout
31//!
32//! The [`Session`] type is implemented across several single-responsibility
33//! submodules and exposed here as a single facade:
34//!
35//! - [`types`] — [`Session`], [`SessionMetadata`], [`ImageAttachment`].
36//! - [`events`] — [`SessionResult`], [`SessionEvent`].
37//! - [`lifecycle`] — constructor, agent/provenance, message append.
38//! - [`persistence`] — save / load / delete / directory lookup.
39//! - [`title`] — title generation and context-change hook.
40//! - [`prompt_api`] — public [`prompt`](Session::prompt) entry points.
41//! - [`context`] — [`DerivedContext`] + [`derive_context`]: produce the
42//!   per-step LLM context from the append-only chat history without
43//!   mutating [`Session::messages`]. See the Phase A plan.
44//! - [`helper`] — the agentic loop implementation (non-public details).
45
46mod bus;
47mod checkpoint;
48mod checkpoint_prompt;
49mod checkpoint_store;
50mod event_compaction;
51mod event_rlm;
52mod event_token;
53mod events;
54mod header;
55pub(crate) mod history_files;
56mod lifecycle;
57mod persistence;
58mod prompt_api;
59pub mod step_limit;
60mod tail_load;
61mod tail_seed;
62mod title;
63pub mod types;
64mod workspace_index;
65mod workspace_index_io;
66
67pub mod codex_import;
68pub mod context;
69pub mod delegation;
70pub mod delegation_skills;
71pub mod derive_policy;
72pub mod eval;
73pub mod faults;
74pub mod helper;
75pub mod history;
76pub mod history_sink;
77pub mod index;
78pub mod index_produce;
79pub mod journal;
80pub mod listing;
81mod listing_all;
82pub mod oracle;
83pub mod oracle_replay;
84pub mod pages;
85pub mod relevance;
86pub mod tasks;
87
88pub use self::bus::{DurableSink, NoopSink, SessionBus};
89pub use self::checkpoint::{CheckpointReason, RunCheckpoint};
90pub use self::checkpoint_prompt::auto_resume_prompt;
91pub use self::codex_import::{
92    import_codex_session_by_id, import_codex_sessions_for_directory, load_or_import_session,
93};
94pub use self::context::{DerivedContext, derive_context, derive_with_policy, effective_policy};
95pub use self::delegation::{BetaPosterior, DelegationConfig, DelegationState};
96pub use self::derive_policy::DerivePolicy;
97pub use self::eval::{PolicyRunResult, pareto_frontier, reuse_rate};
98pub use self::event_compaction::{
99    CompactionFailure, CompactionOutcome, CompactionStart, ContextTruncation, FallbackStrategy,
100};
101pub use self::event_rlm::{RlmCompletion, RlmOutcome, RlmProgressEvent, RlmSubcallFallback};
102pub use self::event_token::{TokenDelta, TokenEstimate, TokenSource};
103pub use self::events::{SessionEvent, SessionResult};
104pub use self::faults::Fault;
105pub use self::history::History;
106pub use self::history_sink::{HistorySinkConfig, PointerHandle};
107pub use self::index::{Granularity, SummaryIndex, SummaryNode, SummaryRange};
108pub use self::journal::{JournalEntry, Op, RejectReason, TxnId, WritebackJournal};
109pub use self::listing::{SessionSummary, list_sessions};
110pub use self::listing_all::list_all_sessions_for_directory;
111pub use self::oracle::{OracleReport, replay_oracle};
112pub use self::pages::{PageKind, ResidencyLevel};
113pub use self::relevance::{
114    Bucket, Dependency, Difficulty, RelevanceMeta, ToolUse, bucket_for_messages,
115};
116pub use self::tail_load::TailLoad;
117pub use self::tasks::{SessionTaskStatus, TaskEvent, TaskLog, TaskState};
118pub use self::types::{DEFAULT_MAX_STEPS, ImageAttachment, Session, SessionMetadata};
119
120#[cfg(test)]
121mod checkpoint_tests;
122#[cfg(test)]
123mod tests;
codetether_agent/session/mod.rs

codetether_agent/session/
mod.rs
