--- adr_number: 20 title: Session Model status_history: - - '2026-02-16' - Proposed - Jeffrey Phillips Freeman - - '2026-02-16' - Accepted - Jeffrey Phillips Freeman tier: 3 authors: - Jeffrey Phillips Freeman superseded_by: null related_adrs: - number: 6 title: Plan Lifecycle relationship: Plans execute within sessions and inherit session-scoped context - number: 10 title: Actor and Agent Architecture relationship: Sessions bind a user to an orchestrator actor for conversation - number: 14 title: Context Management (ACMS) relationship: Sessions maintain session-scoped context tiers and conversation history - number: 26 title: Agent-to-Agent Protocol (A2A) relationship: A2A exposes session lifecycle operations to all clients acceptance: votes_for: - voter: Jeffrey Phillips Freeman comment: Sessions as persistent conversation threads with cost budgets and context scoping tie the user experience together votes_against: [] abstentions: [] --- ## Context Users interact with CleverAgents through conversations — asking questions, giving instructions, reviewing plan outputs, and providing corrections. These conversations need persistent state: the current orchestrator actor, the conversation history, the active plan context, and accumulated knowledge. The system needs a session abstraction that binds a conversation to an orchestrator actor and provides session-scoped context, budgets, and lifecycle management. ## Decision Drivers - Conversations must persist across CLI restarts so users can resume multi-turn interactions - Each session needs a bound orchestrator actor that provides a consistent conversational personality - Session-scoped cost budgets must aggregate across all plans within a session to prevent cost overruns - Accumulated knowledge and conversation history must be available across plan boundaries within a session - Session lifecycle (create, resume, archive) must be explicitly manageable by users ## Decision A **session** is a persistent conversation thread that binds a user to an **orchestrator actor** and provides session-scoped context, cost budgets, and conversation history. Sessions are the top-level interactive abstraction — plans are executed within the context of a session. ## Design ### Session Identity Each session has: - **`session_id`**: ULID, unique identifier. - **`name`**: Optional human-readable label for the session. - **`created_at`** / **`updated_at`**: Timestamps. - **`created_by`**: User identity. ### Orchestrator Binding Every session is bound to an **orchestrator actor** — the actor that drives the conversation. The orchestrator: - Receives user messages and routes them to appropriate actions. - Can invoke `plan use`, `plan execute`, `plan apply`, and other commands on behalf of the user. - Maintains conversational context across turns. - May delegate to specialized actors via actor composition. The default orchestrator is configured via `actor.default.orchestrator`. Sessions created without an explicit `--actor` flag use this default. ### Session Lifecycle Sessions are created via `agents session new` (or implicitly when the user starts a conversation). Sessions persist across CLI invocations — the user can resume a session by ID or name. Sessions can be listed, shown, and archived. ### Session-Scoped Context Sessions maintain their own context: - **Conversation history**: The sequence of user messages and actor responses. - **Active plans**: Plans currently being worked on within this session. - **Session knowledge**: Accumulated facts and preferences learned during the conversation. - **Session budget**: Maximum estimated API cost per session (`plan.budget.per-session`). When cumulative session cost exceeds this budget, all plan operations pause. ### Session and Plan Relationship Plans are executed within sessions. A session may have multiple active plans (sequential or concurrent). The session provides: - The orchestrator actor for interactive plan management. - Session-level budget tracking across all plans. - Conversation context that persists across plan boundaries. ### Session Commands | Command | Description | |---------|-------------| | `agents session new [--actor ]` | Create a new session | | `agents session list` | List sessions | | `agents session show ` | Show session details | | `agents session resume ` | Resume a session | | `agents session archive ` | Archive a session | ## Constraints - Every interactive conversation must have a session. There is no "sessionless" interaction mode. - Sessions are bound to exactly one orchestrator actor at creation time. The binding cannot be changed after creation. - Session budget (`plan.budget.per-session`) is an aggregate across all plans within the session. - Session conversation history must be persisted to the database, not held only in memory. - Session IDs are ULIDs, consistent with all other entity identifiers. ## Consequences ### Positive - Persistent sessions enable long-running conversations that survive CLI restarts. - Session-scoped budgets prevent cost overruns across multiple plans. - Orchestrator binding provides a consistent conversational personality and capability set. - Conversation history enables context-aware interactions across plan boundaries. ### Negative - Session management adds another entity type to the system with its own lifecycle and storage requirements. - The orchestrator binding is immutable after creation, which may be limiting if the user wants to switch interaction styles mid-session. - Session-scoped context accumulates over time and may need periodic cleanup or summarization to remain useful. ### Risks - Long-running sessions could accumulate excessive conversation history, consuming storage and degrading context retrieval quality. - Session budget tracking requires accurate cost estimation, which depends on LLM provider pricing accuracy. - Orphaned sessions (created but never used or resumed) could accumulate in the database without cleanup. ## Alternatives Considered **Stateless interactions (no session persistence)** — Every CLI invocation would start fresh with no conversation context. This prevents multi-turn interactions, accumulated knowledge, and session-scoped budgets. **Implicit sessions (auto-created, auto-destroyed)** — Simpler but prevents intentional session management (naming, archiving, resuming). The explicit session model gives users control over their conversation state. ## Compliance - **Session lifecycle tests**: Tests verify creation, resumption, archival, and listing of sessions. - **Budget enforcement tests**: Tests verify that session-scoped budgets correctly aggregate across plans and pause operations when exceeded. - **Persistence tests**: Tests verify that conversation history survives CLI restarts and is correctly loaded on session resumption. - **Orchestrator binding tests**: Tests verify that the orchestrator actor is correctly bound at creation and that all session interactions route through it. - **Cleanup tests**: Tests verify that session archival correctly marks sessions as inactive without data loss.