UAT: TUI session persistence (SQLite at ~/.local/state/cleveragents/tui.db) not implemented — no persistence layer exists #3284

Open
opened 2026-04-05 09:08:08 +00:00 by freemo · 2 comments
Owner

Metadata

  • Branch: bugfix/m8-tui-session-persistence
  • Commit Message: fix(tui): implement SQLite session persistence at ~/.local/state/cleveragents/tui.db
  • Milestone: None (Backlog)
  • Parent Epic: #868

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background and Context

Per ADR-044 (TUI Architecture and Framework), the v3.7.0 milestone scope explicitly requires session persistence for the TUI. Inspection of the TUI source tree at src/cleveragents/tui/ and all open PRs (including PR #1294 feature/m8-tui-materializer and PR #1302 feature/m8-tui-mainscreen) reveals that no session persistence implementation exists anywhere in the codebase.

Feature Area: TUI Implementation (v3.7.0 — M8)
Severity: High

Current Behavior

No session persistence implementation exists anywhere in the codebase or in any open PR:

  • No SQLite database module for TUI sessions exists (src/cleveragents/tui/session_store.py is absent)
  • No ~/.local/state/cleveragents/tui.db creation or management code exists
  • The SessionsScreen (ctrl+s) is not implemented — screens/ directory only has main_screen.py in the PR branches
  • ctrl+r keybinding for session resume is not bound in MainScreen
  • On app restart, no session restoration occurs — the app always starts fresh
  • action_new_session() and action_close_session() in PR #1302 are stubs with no persistence backing

Steps to Reproduce:

  1. Launch the TUI (agents tui)
  2. Have a conversation
  3. Close the TUI (ctrl+q)
  4. Relaunch the TUI
  5. Expected: previous session restored; Actual: fresh empty session

Expected Behavior

Per ADR-044 and the v3.7.0 milestone scope:

  • Session persistence is backed by SQLite at ~/.local/state/cleveragents/tui.db
  • Session state is persisted across TUI restarts
  • On subsequent launches, the TUI restores the last active persona and session
  • ctrl+r opens the SessionsScreen to resume a previous session
  • ctrl+w closes a session tab (with confirmation if unsaved)

Acceptance Criteria

  • src/cleveragents/tui/session_store.py implements SQLite-backed session persistence at ~/.local/state/cleveragents/tui.db
  • TUI restores the last active session on startup
  • ctrl+r opens SessionsScreen to resume a previous session
  • SessionsScreen (src/cleveragents/tui/screens/sessions.py) is implemented
  • Session tabs can be closed with ctrl+w (with confirmation if unsaved)

Supporting Information

  • Code Location: src/cleveragents/tui/ — no session_store.py, no persistence module
  • Code Location: src/cleveragents/tui/screens/ — no sessions.py (SessionsScreen)
  • PR #1302 (feature/m8-tui-mainscreen): action_new_session() and action_close_session() are stubs; no ctrl+r binding
  • ADR-044: TUI Architecture and Framework — defines session persistence requirements
  • Related Issues: #3223 (TUI screens/ directory is empty), #3272 (TUI MainScreen sidebar not implemented), #3273 (TUI TuiCommandRouter cannot dispatch colon-namespaced slash commands)

Subtasks

  • Create src/cleveragents/tui/session_store.py with SQLite-backed SessionStore class
  • Implement DB schema: sessions table with id, persona, messages, created_at, updated_at
  • Implement ~/.local/state/cleveragents/ directory creation on first launch
  • Wire SessionStore into MainScreen for auto-save on message send and session close
  • Implement session restoration on TUI startup (load last active session)
  • Create src/cleveragents/tui/screens/sessions.py with SessionsScreen widget
  • Bind ctrl+r in MainScreen to open SessionsScreen
  • Bind ctrl+w in MainScreen to close current session tab (with unsaved-changes confirmation)
  • Tests (Behave): Add scenarios for session persistence, restore on startup, and ctrl+r/ctrl+w keybindings
  • Tests (Robot): Add integration test for full session lifecycle (create → persist → restore)
  • Verify coverage ≥ 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(tui): implement SQLite session persistence at ~/.local/state/cleveragents/tui.db), followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (bugfix/m8-tui-session-persistence).
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `bugfix/m8-tui-session-persistence` - **Commit Message**: `fix(tui): implement SQLite session persistence at ~/.local/state/cleveragents/tui.db` - **Milestone**: None (Backlog) - **Parent Epic**: #868 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context Per ADR-044 (TUI Architecture and Framework), the v3.7.0 milestone scope explicitly requires session persistence for the TUI. Inspection of the TUI source tree at `src/cleveragents/tui/` and all open PRs (including PR #1294 `feature/m8-tui-materializer` and PR #1302 `feature/m8-tui-mainscreen`) reveals that no session persistence implementation exists anywhere in the codebase. **Feature Area:** TUI Implementation (v3.7.0 — M8) **Severity:** High ## Current Behavior No session persistence implementation exists anywhere in the codebase or in any open PR: - No SQLite database module for TUI sessions exists (`src/cleveragents/tui/session_store.py` is absent) - No `~/.local/state/cleveragents/tui.db` creation or management code exists - The `SessionsScreen` (`ctrl+s`) is not implemented — `screens/` directory only has `main_screen.py` in the PR branches - `ctrl+r` keybinding for session resume is not bound in `MainScreen` - On app restart, no session restoration occurs — the app always starts fresh - `action_new_session()` and `action_close_session()` in PR #1302 are stubs with no persistence backing **Steps to Reproduce:** 1. Launch the TUI (`agents tui`) 2. Have a conversation 3. Close the TUI (`ctrl+q`) 4. Relaunch the TUI 5. **Expected:** previous session restored; **Actual:** fresh empty session ## Expected Behavior Per ADR-044 and the v3.7.0 milestone scope: - Session persistence is backed by SQLite at `~/.local/state/cleveragents/tui.db` - Session state is persisted across TUI restarts - On subsequent launches, the TUI restores the last active persona and session - `ctrl+r` opens the `SessionsScreen` to resume a previous session - `ctrl+w` closes a session tab (with confirmation if unsaved) ## Acceptance Criteria - [ ] `src/cleveragents/tui/session_store.py` implements SQLite-backed session persistence at `~/.local/state/cleveragents/tui.db` - [ ] TUI restores the last active session on startup - [ ] `ctrl+r` opens `SessionsScreen` to resume a previous session - [ ] `SessionsScreen` (`src/cleveragents/tui/screens/sessions.py`) is implemented - [ ] Session tabs can be closed with `ctrl+w` (with confirmation if unsaved) ## Supporting Information - **Code Location:** `src/cleveragents/tui/` — no `session_store.py`, no persistence module - **Code Location:** `src/cleveragents/tui/screens/` — no `sessions.py` (`SessionsScreen`) - **PR #1302** (`feature/m8-tui-mainscreen`): `action_new_session()` and `action_close_session()` are stubs; no `ctrl+r` binding - **ADR-044:** TUI Architecture and Framework — defines session persistence requirements - **Related Issues:** #3223 (TUI `screens/` directory is empty), #3272 (TUI MainScreen sidebar not implemented), #3273 (TUI `TuiCommandRouter` cannot dispatch colon-namespaced slash commands) ## Subtasks - [ ] Create `src/cleveragents/tui/session_store.py` with SQLite-backed `SessionStore` class - [ ] Implement DB schema: sessions table with id, persona, messages, created_at, updated_at - [ ] Implement `~/.local/state/cleveragents/` directory creation on first launch - [ ] Wire `SessionStore` into `MainScreen` for auto-save on message send and session close - [ ] Implement session restoration on TUI startup (load last active session) - [ ] Create `src/cleveragents/tui/screens/sessions.py` with `SessionsScreen` widget - [ ] Bind `ctrl+r` in `MainScreen` to open `SessionsScreen` - [ ] Bind `ctrl+w` in `MainScreen` to close current session tab (with unsaved-changes confirmation) - [ ] Tests (Behave): Add scenarios for session persistence, restore on startup, and `ctrl+r`/`ctrl+w` keybindings - [ ] Tests (Robot): Add integration test for full session lifecycle (create → persist → restore) - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(tui): implement SQLite session persistence at ~/.local/state/cleveragents/tui.db`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`bugfix/m8-tui-session-persistence`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
freemo added this to the v3.7.0 milestone 2026-04-05 09:23:03 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified — well-documented missing feature with clear ADR-044 references and code analysis
  • Priority: Backlog (unchanged) — TUI session persistence is M8 scope, which is lower priority than M1-M6
  • Milestone: v3.7.0 — TUI implementation is M8 scope per ADR-044
  • MoSCoW: Should Have — session persistence is explicitly listed in the v3.7.0 milestone scope description. Required for a complete TUI experience but M8 is not the current focus.
  • Parent Epic: #868 (referenced in issue body)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified — well-documented missing feature with clear ADR-044 references and code analysis - **Priority**: Backlog (unchanged) — TUI session persistence is M8 scope, which is lower priority than M1-M6 - **Milestone**: v3.7.0 — TUI implementation is M8 scope per ADR-044 - **MoSCoW**: Should Have — session persistence is explicitly listed in the v3.7.0 milestone scope description. Required for a complete TUI experience but M8 is not the current focus. - **Parent Epic**: #868 (referenced in issue body) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium (upgrading from Backlog — session persistence is a core M8 requirement per ADR-044, but the TUI milestone has no deadline and the milestone description says to focus on M1-M6 first)
  • Milestone: v3.7.0 (this is explicitly M8 TUI scope — session persistence is listed in the v3.7.0 milestone description)
  • MoSCoW: Must Have — the v3.7.0 milestone scope explicitly lists "Session persistence (SQLite at ~/.local/state/cleveragents/tui.db)" as a required feature. Without this, the TUI cannot maintain state across restarts, which is a fundamental usability requirement.
  • Parent Epic: #868 (TUI Interface, Modals and Persona System)

This is a well-documented feature gap with clear ADR references and comprehensive subtasks. The issue correctly identifies that no persistence layer exists anywhere in the codebase. However, given that all dated milestones (v3.2.0-v3.6.0) are overdue, this should not be prioritized over those milestones' Must Have items.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium (upgrading from Backlog — session persistence is a core M8 requirement per ADR-044, but the TUI milestone has no deadline and the milestone description says to focus on M1-M6 first) - **Milestone**: v3.7.0 (this is explicitly M8 TUI scope — session persistence is listed in the v3.7.0 milestone description) - **MoSCoW**: Must Have — the v3.7.0 milestone scope explicitly lists "Session persistence (SQLite at ~/.local/state/cleveragents/tui.db)" as a required feature. Without this, the TUI cannot maintain state across restarts, which is a fundamental usability requirement. - **Parent Epic**: #868 (TUI Interface, Modals and Persona System) This is a well-documented feature gap with clear ADR references and comprehensive subtasks. The issue correctly identifies that no persistence layer exists anywhere in the codebase. However, given that all dated milestones (v3.2.0-v3.6.0) are overdue, this should not be prioritized over those milestones' Must Have items. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
freemo removed this from the v3.7.0 milestone 2026-04-07 00:10:45 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#3284
No description provided.