bug(tui): TUI Sessions screen (ctrl+s) not implemented — screens/ empty, binding missing, slash commands unhandled #3011

Open
opened 2026-04-05 03:41:32 +00:00 by freemo · 1 comment
Owner

Background and Context

The TUI Sessions screen is specified as a core feature of the CleverAgents TUI (see docs/specification.md section "Sessions Screen"). It provides multi-session management via a modal overlay accessible via ctrl+s, and is also driven by a suite of /session:* slash commands. Currently, the feature is entirely absent from the codebase.

Current Behavior

Three distinct defects combine to make the Sessions screen completely non-functional:

  1. screens/ directory is empty: src/cleveragents/tui/screens/ contains only a __pycache__ directory — no SessionsScreen or any other screen implementation exists.

  2. ctrl+s binding missing: src/cleveragents/tui/app.py (lines 92–95) only defines three key bindings: ctrl+q (quit), f1 (help), and ctrl+t (cycle preset). The spec requires ctrl+s to open the Sessions screen. Pressing ctrl+s does nothing.

  3. Session slash commands not handled: TuiCommandRouter._session_command() in src/cleveragents/tui/commands.py only handles show, export, and import sub-commands. The following slash commands are catalogued in slash_catalog.py but produce "Unknown session command: <sub-command>" errors at runtime:

    • /session:create — Create a new session tab
    • /session:switch — Switch to a session
    • /session:close — Close the current session
    • /session:delete — Delete a saved session
    • /session:rename — Rename current session
    • /session:list — Display all sessions

Expected Behavior

Per docs/specification.md section "Sessions Screen":

  • ctrl+s opens a modal overlay showing all active and saved sessions.
  • The Sessions screen shows Active Sessions (top panel) and Saved Sessions (bottom panel).
  • Each session entry displays: name, persona, actor, status indicator, last prompt preview, and timestamp.
  • Key bindings within the screen: enter Switch, ctrl+r Resume saved, ctrl+n New, d Delete, r Rename, esc Back.
  • All session slash commands (/session:create, /session:switch, /session:close, /session:delete, /session:rename, /session:list) are fully functional and route correctly through TuiCommandRouter.

Acceptance Criteria

  • src/cleveragents/tui/screens/sessions.py exists and implements SessionsScreen as a Textual modal screen.
  • SessionsScreen renders Active Sessions (top) and Saved Sessions (bottom) panels with the fields specified above.
  • All key bindings within SessionsScreen (enter, ctrl+r, ctrl+n, d, r, esc) are implemented and functional.
  • ctrl+s binding is registered in src/cleveragents/tui/app.py BINDINGS and opens SessionsScreen.
  • TuiCommandRouter._session_command() handles create, switch, close, delete, rename, and list sub-commands without raising "Unknown session command" errors.
  • All new code is fully statically typed and passes nox -e typecheck (Pyright).
  • Behave BDD scenarios cover: opening the screen via ctrl+s, each slash command sub-command, and all in-screen key bindings.
  • Robot Framework integration tests cover the end-to-end session management flow.
  • nox -e coverage_report reports coverage ≥ 97%.
  • All default nox sessions pass with no errors.

Supporting Information

Affected files:

  • src/cleveragents/tui/screens/ — directory is empty (only __pycache__)
  • src/cleveragents/tui/app.py lines 92–95 — BINDINGS list missing ctrl+s
  • src/cleveragents/tui/commands.py _session_command() — missing handlers for create/switch/close/delete/rename/list
  • src/cleveragents/tui/slash_catalog.py — catalogs the six unhandled /session:* commands

Severity: High — the Sessions screen is a core TUI feature for multi-session management.

Related ADRs: ADR-044 (TUI Architecture), ADR-046 (Reference/Command System)

Metadata

  • Branch: fix/tui-sessions-screen-not-implemented
  • Commit Message: fix(tui): implement SessionsScreen, ctrl+s binding, and session slash commands
  • Milestone: v3.7.0
  • Parent Epic: #868

Subtasks

  • TDD: Write @tdd_expected_fail Behave scenario proving ctrl+s does nothing (issue-capture test)
  • TDD: Write @tdd_expected_fail Behave scenarios for each unhandled /session:* slash command
  • Implement src/cleveragents/tui/screens/sessions.pySessionsScreen Textual modal with Active/Saved panels
  • Implement all in-screen key bindings: enter Switch, ctrl+r Resume, ctrl+n New, d Delete, r Rename, esc Back
  • Register ctrl+s binding in src/cleveragents/tui/app.py BINDINGS and wire to SessionsScreen
  • Implement create, switch, close, delete, rename, list handlers in TuiCommandRouter._session_command()
  • Add __init__.py export for SessionsScreen in src/cleveragents/tui/screens/
  • Tests (Behave): Add/update scenarios for ctrl+s screen launch, all slash command sub-commands, and in-screen key bindings
  • Tests (Robot): Add integration test for end-to-end session management flow
  • Verify all new code passes nox -e typecheck (Pyright, no # type: ignore)
  • Verify coverage ≥ 97% via nox -e 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 SessionsScreen, ctrl+s binding, and session slash commands), followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit footer includes ISSUES CLOSED: #<this issue number>.
  • The commit is pushed to the remote on the branch fix/tui-sessions-screen-not-implemented.
  • 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

## Background and Context The TUI Sessions screen is specified as a core feature of the CleverAgents TUI (see `docs/specification.md` section "Sessions Screen"). It provides multi-session management via a modal overlay accessible via `ctrl+s`, and is also driven by a suite of `/session:*` slash commands. Currently, the feature is entirely absent from the codebase. ## Current Behavior Three distinct defects combine to make the Sessions screen completely non-functional: 1. **`screens/` directory is empty**: `src/cleveragents/tui/screens/` contains only a `__pycache__` directory — no `SessionsScreen` or any other screen implementation exists. 2. **`ctrl+s` binding missing**: `src/cleveragents/tui/app.py` (lines 92–95) only defines three key bindings: `ctrl+q` (quit), `f1` (help), and `ctrl+t` (cycle preset). The spec requires `ctrl+s` to open the Sessions screen. Pressing `ctrl+s` does nothing. 3. **Session slash commands not handled**: `TuiCommandRouter._session_command()` in `src/cleveragents/tui/commands.py` only handles `show`, `export`, and `import` sub-commands. The following slash commands are catalogued in `slash_catalog.py` but produce `"Unknown session command: <sub-command>"` errors at runtime: - `/session:create` — Create a new session tab - `/session:switch` — Switch to a session - `/session:close` — Close the current session - `/session:delete` — Delete a saved session - `/session:rename` — Rename current session - `/session:list` — Display all sessions ## Expected Behavior Per `docs/specification.md` section "Sessions Screen": - `ctrl+s` opens a modal overlay showing all active and saved sessions. - The Sessions screen shows **Active Sessions** (top panel) and **Saved Sessions** (bottom panel). - Each session entry displays: name, persona, actor, status indicator, last prompt preview, and timestamp. - Key bindings within the screen: `enter` Switch, `ctrl+r` Resume saved, `ctrl+n` New, `d` Delete, `r` Rename, `esc` Back. - All session slash commands (`/session:create`, `/session:switch`, `/session:close`, `/session:delete`, `/session:rename`, `/session:list`) are fully functional and route correctly through `TuiCommandRouter`. ## Acceptance Criteria - [ ] `src/cleveragents/tui/screens/sessions.py` exists and implements `SessionsScreen` as a Textual modal screen. - [ ] `SessionsScreen` renders Active Sessions (top) and Saved Sessions (bottom) panels with the fields specified above. - [ ] All key bindings within `SessionsScreen` (`enter`, `ctrl+r`, `ctrl+n`, `d`, `r`, `esc`) are implemented and functional. - [ ] `ctrl+s` binding is registered in `src/cleveragents/tui/app.py` BINDINGS and opens `SessionsScreen`. - [ ] `TuiCommandRouter._session_command()` handles `create`, `switch`, `close`, `delete`, `rename`, and `list` sub-commands without raising "Unknown session command" errors. - [ ] All new code is fully statically typed and passes `nox -e typecheck` (Pyright). - [ ] Behave BDD scenarios cover: opening the screen via `ctrl+s`, each slash command sub-command, and all in-screen key bindings. - [ ] Robot Framework integration tests cover the end-to-end session management flow. - [ ] `nox -e coverage_report` reports coverage ≥ 97%. - [ ] All default `nox` sessions pass with no errors. ## Supporting Information **Affected files:** - `src/cleveragents/tui/screens/` — directory is empty (only `__pycache__`) - `src/cleveragents/tui/app.py` lines 92–95 — BINDINGS list missing `ctrl+s` - `src/cleveragents/tui/commands.py` `_session_command()` — missing handlers for `create`/`switch`/`close`/`delete`/`rename`/`list` - `src/cleveragents/tui/slash_catalog.py` — catalogs the six unhandled `/session:*` commands **Severity**: High — the Sessions screen is a core TUI feature for multi-session management. **Related ADRs**: ADR-044 (TUI Architecture), ADR-046 (Reference/Command System) ## Metadata - **Branch**: `fix/tui-sessions-screen-not-implemented` - **Commit Message**: `fix(tui): implement SessionsScreen, ctrl+s binding, and session slash commands` - **Milestone**: v3.7.0 - **Parent Epic**: #868 ## Subtasks - [ ] TDD: Write `@tdd_expected_fail` Behave scenario proving `ctrl+s` does nothing (issue-capture test) - [ ] TDD: Write `@tdd_expected_fail` Behave scenarios for each unhandled `/session:*` slash command - [ ] Implement `src/cleveragents/tui/screens/sessions.py` — `SessionsScreen` Textual modal with Active/Saved panels - [ ] Implement all in-screen key bindings: `enter` Switch, `ctrl+r` Resume, `ctrl+n` New, `d` Delete, `r` Rename, `esc` Back - [ ] Register `ctrl+s` binding in `src/cleveragents/tui/app.py` BINDINGS and wire to `SessionsScreen` - [ ] Implement `create`, `switch`, `close`, `delete`, `rename`, `list` handlers in `TuiCommandRouter._session_command()` - [ ] Add `__init__.py` export for `SessionsScreen` in `src/cleveragents/tui/screens/` - [ ] Tests (Behave): Add/update scenarios for `ctrl+s` screen launch, all slash command sub-commands, and in-screen key bindings - [ ] Tests (Robot): Add integration test for end-to-end session management flow - [ ] Verify all new code passes `nox -e typecheck` (Pyright, no `# type: ignore`) - [ ] Verify coverage ≥ 97% via `nox -e 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 SessionsScreen, ctrl+s binding, and session slash commands`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit footer includes `ISSUES CLOSED: #<this issue number>`. - The commit is pushed to the remote on the branch `fix/tui-sessions-screen-not-implemented`. - 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 03:43:35 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Confirmed
  • MoSCoW: Should Have

Valid finding verified during batch triage.


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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
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#3011
No description provided.