feat(tui): implement first-run actor selection overlay for initial persona setup #9306

New issue

Open

opened 2026-04-14 14:34:26 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-14 14:34:26 +00:00

Owner

Metadata

Branch: feat/tui-first-run-actor-selection-overlay
Commit message: feat(tui): implement first-run actor selection overlay for initial persona setup
Milestone: v3.7.0
Related bug: #1350 (UAT: First-run experience — actor selection overlay not implemented)

Background and Context

The TUI specification (§First-Run Experience) defines a guided onboarding overlay that appears on first launch when no personas are configured. Currently, as documented in bug #1350, the on_mount() method in src/cleveragents/tui/app.py performs no first-run detection, and PersonaRegistry.ensure_default() silently creates a "default" persona using actor="local/mock-default" — a non-functional mock — without any user interaction.

This means every new user who launches the TUI for the first time is silently dropped into a broken state with a mock actor, rather than being guided through selecting a real, working actor. The first-run overlay is a critical UX gate that must be implemented to make the TUI usable out of the box.

The overlay must integrate with the existing Textual-based MainScreen, respect the Dracula theme, and write the resulting persona to the YAML-based persona registry so that subsequent launches restore the last active persona automatically.

Expected Behavior

On first launch (no personas configured in ~/.config/cleveragents/personas/):

A centered modal overlay appears over the MainScreen before any other interaction is possible.
The overlay displays a curated list of available actors:
- anthropic/claude-4-sonnet (recommended, highlighted by default)
- anthropic/claude-4-opus
- openai/gpt-4o
- openai/o3
- google/gemini-2
The user can navigate with j/k (or arrow keys), and type / to enter a search/filter mode.
Pressing Enter on a selected actor:
- Creates a "default" persona YAML file with the chosen actor.
- Auto-generates argument presets (e.g., thinking effort levels) by introspecting the actor's argument schema.
- Writes the persona to the registry.
The overlay closes and the main TUI becomes fully interactive.
On all subsequent launches, the last active persona is restored from the registry — the overlay does not appear again.

Visual specification (from §First-Run Experience):

┌──────────────────────────────────────────────────────────────────────┐
│ Welcome to CleverAgents                                              │
│                                                                      │
│ Select an actor to get started:                                      │
│                                                                      │
│   ❯ anthropic/claude-4-sonnet   (recommended)                        │
│     anthropic/claude-4-opus                                          │
│     openai/gpt-4o                                                    │
│     openai/o3                                                        │
│     google/gemini-2                                                  │
│     / to search...                                                   │
│                                                                      │
│ A default persona will be created with this actor.                   │
│ You can add more actors and personas later.                          │
│                                                                      │
│──────────────────────────────────────────────────────────────────────│
│ enter Select │ j/k Navigate │ / Search                               │
└──────────────────────────────────────────────────────────────────────┘

Acceptance Criteria

A FirstRunOverlay Textual widget exists in src/cleveragents/tui/overlays/first_run.py (or equivalent path).
MainScreen.on_mount() detects first-run condition (no personas in registry) and mounts the FirstRunOverlay before yielding control to the user.
The overlay renders a scrollable list of the five curated actors with anthropic/claude-4-sonnet pre-selected.
j/k (and ↑/↓) navigate the actor list; cursor wraps at boundaries.
/ key activates an inline search/filter input that narrows the displayed actor list in real time.
Enter on a selected actor creates a "default" persona YAML with the chosen actor and auto-generated presets.
Auto-generated presets are derived from the actor's argument schema (e.g., thinking_effort: low/medium/high where supported).
After persona creation, the overlay is dismissed and MainScreen becomes fully interactive.
PersonaRegistry.ensure_default() is updated (or bypassed) so it no longer silently creates a local/mock-default persona on first run.
Subsequent launches with an existing "default" persona skip the overlay entirely and restore the last active persona.
The overlay is styled with the Dracula theme (consistent with the rest of the TUI).
Unit tests cover: first-run detection, actor list rendering, j/k navigation, / search filtering, Enter persona creation, and overlay dismissal.
Integration test verifies end-to-end: empty config dir → overlay appears → actor selected → persona file written → overlay dismissed → TUI ready.

Subtasks

Audit on_mount() and ensure_default() — document the exact code paths that bypass first-run detection (src/cleveragents/tui/app.py lines 120–127, src/cleveragents/tui/persona/registry.py lines 205–212).
Design FirstRunOverlay widget — create src/cleveragents/tui/overlays/first_run.py with a FirstRunOverlay(ModalScreen) class; define the actor list data structure and curated defaults.
Implement actor list rendering — render the five curated actors with a ❯ cursor indicator; apply Dracula theme colours (purple highlight for selected row).
Implement j/k / arrow-key navigation — handle Key events; wrap cursor at top/bottom of list.
Implement / search mode — on / keypress, show an inline Input widget; filter actor list reactively as the user types; Escape exits search and restores full list.
Implement Enter persona creation — on confirmation, call PersonaRegistry to write the "default" persona YAML with the selected actor; introspect actor argument schema to auto-generate presets.
Update PersonaRegistry.ensure_default() — remove or guard the silent local/mock-default fallback; add a has_any_persona() helper for first-run detection.
Wire overlay into MainScreen.on_mount() — check registry.has_any_persona(); if False, push FirstRunOverlay and await its result before proceeding.
Write unit tests — cover all acceptance criteria items; mock PersonaRegistry and actor schema introspection.
Write integration test — spin up TUI with empty config dir, simulate actor selection, assert persona file created and overlay dismissed.
Manual QA — verify Dracula theme, block cursor, keyboard navigation, and search on a real terminal.

Definition of Done

All acceptance criteria checkboxes are checked.
All subtasks are complete.
CI passes (lint, unit tests, integration tests).
The FirstRunOverlay is visually consistent with the Dracula-themed TUI (reviewed by a team member).
Bug #1350 can be closed as resolved (verified by a manual first-run test on a clean config directory).
No regression: existing users with configured personas see no change in behaviour.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch**: `feat/tui-first-run-actor-selection-overlay` - **Commit message**: `feat(tui): implement first-run actor selection overlay for initial persona setup` - **Milestone**: v3.7.0 - **Related bug**: #1350 (UAT: First-run experience — actor selection overlay not implemented) --- ## Background and Context The TUI specification (§First-Run Experience) defines a guided onboarding overlay that appears on first launch when no personas are configured. Currently, as documented in bug #1350, the `on_mount()` method in `src/cleveragents/tui/app.py` performs no first-run detection, and `PersonaRegistry.ensure_default()` silently creates a `"default"` persona using `actor="local/mock-default"` — a non-functional mock — without any user interaction. This means every new user who launches the TUI for the first time is silently dropped into a broken state with a mock actor, rather than being guided through selecting a real, working actor. The first-run overlay is a critical UX gate that must be implemented to make the TUI usable out of the box. The overlay must integrate with the existing Textual-based `MainScreen`, respect the Dracula theme, and write the resulting persona to the YAML-based persona registry so that subsequent launches restore the last active persona automatically. --- ## Expected Behavior On first launch (no personas configured in `~/.config/cleveragents/personas/`): 1. A centered modal overlay appears over the `MainScreen` before any other interaction is possible. 2. The overlay displays a curated list of available actors: - `anthropic/claude-4-sonnet` (recommended, highlighted by default) - `anthropic/claude-4-opus` - `openai/gpt-4o` - `openai/o3` - `google/gemini-2` 3. The user can navigate with `j`/`k` (or arrow keys), and type `/` to enter a search/filter mode. 4. Pressing `Enter` on a selected actor: - Creates a `"default"` persona YAML file with the chosen actor. - Auto-generates argument presets (e.g., thinking effort levels) by introspecting the actor's argument schema. - Writes the persona to the registry. 5. The overlay closes and the main TUI becomes fully interactive. 6. On all subsequent launches, the last active persona is restored from the registry — the overlay does **not** appear again. Visual specification (from §First-Run Experience): ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Welcome to CleverAgents │ │ │ │ Select an actor to get started: │ │ │ │ ❯ anthropic/claude-4-sonnet (recommended) │ │ anthropic/claude-4-opus │ │ openai/gpt-4o │ │ openai/o3 │ │ google/gemini-2 │ │ / to search... │ │ │ │ A default persona will be created with this actor. │ │ You can add more actors and personas later. │ │ │ │──────────────────────────────────────────────────────────────────────│ │ enter Select │ j/k Navigate │ / Search │ └──────────────────────────────────────────────────────────────────────┘ ``` --- ## Acceptance Criteria - [ ] A `FirstRunOverlay` Textual widget exists in `src/cleveragents/tui/overlays/first_run.py` (or equivalent path). - [ ] `MainScreen.on_mount()` detects first-run condition (no personas in registry) and mounts the `FirstRunOverlay` before yielding control to the user. - [ ] The overlay renders a scrollable list of the five curated actors with `anthropic/claude-4-sonnet` pre-selected. - [ ] `j`/`k` (and `↑`/`↓`) navigate the actor list; cursor wraps at boundaries. - [ ] `/` key activates an inline search/filter input that narrows the displayed actor list in real time. - [ ] `Enter` on a selected actor creates a `"default"` persona YAML with the chosen actor and auto-generated presets. - [ ] Auto-generated presets are derived from the actor's argument schema (e.g., `thinking_effort: low/medium/high` where supported). - [ ] After persona creation, the overlay is dismissed and `MainScreen` becomes fully interactive. - [ ] `PersonaRegistry.ensure_default()` is updated (or bypassed) so it no longer silently creates a `local/mock-default` persona on first run. - [ ] Subsequent launches with an existing `"default"` persona skip the overlay entirely and restore the last active persona. - [ ] The overlay is styled with the Dracula theme (consistent with the rest of the TUI). - [ ] Unit tests cover: first-run detection, actor list rendering, `j`/`k` navigation, `/` search filtering, `Enter` persona creation, and overlay dismissal. - [ ] Integration test verifies end-to-end: empty config dir → overlay appears → actor selected → persona file written → overlay dismissed → TUI ready. --- ## Subtasks - [ ] **Audit `on_mount()` and `ensure_default()`** — document the exact code paths that bypass first-run detection (`src/cleveragents/tui/app.py` lines 120–127, `src/cleveragents/tui/persona/registry.py` lines 205–212). - [ ] **Design `FirstRunOverlay` widget** — create `src/cleveragents/tui/overlays/first_run.py` with a `FirstRunOverlay(ModalScreen)` class; define the actor list data structure and curated defaults. - [ ] **Implement actor list rendering** — render the five curated actors with a `❯` cursor indicator; apply Dracula theme colours (purple highlight for selected row). - [ ] **Implement `j`/`k` / arrow-key navigation** — handle `Key` events; wrap cursor at top/bottom of list. - [ ] **Implement `/` search mode** — on `/` keypress, show an inline `Input` widget; filter actor list reactively as the user types; `Escape` exits search and restores full list. - [ ] **Implement `Enter` persona creation** — on confirmation, call `PersonaRegistry` to write the `"default"` persona YAML with the selected actor; introspect actor argument schema to auto-generate presets. - [ ] **Update `PersonaRegistry.ensure_default()`** — remove or guard the silent `local/mock-default` fallback; add a `has_any_persona()` helper for first-run detection. - [ ] **Wire overlay into `MainScreen.on_mount()`** — check `registry.has_any_persona()`; if `False`, push `FirstRunOverlay` and await its result before proceeding. - [ ] **Write unit tests** — cover all acceptance criteria items; mock `PersonaRegistry` and actor schema introspection. - [ ] **Write integration test** — spin up TUI with empty config dir, simulate actor selection, assert persona file created and overlay dismissed. - [ ] **Manual QA** — verify Dracula theme, block cursor, keyboard navigation, and search on a real terminal. --- ## Definition of Done - All acceptance criteria checkboxes are checked. - All subtasks are complete. - CI passes (lint, unit tests, integration tests). - The `FirstRunOverlay` is visually consistent with the Dracula-themed TUI (reviewed by a team member). - Bug #1350 can be closed as resolved (verified by a manual first-run test on a clean config directory). - No regression: existing users with configured personas see no change in behaviour. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-14 14:36:29 +00:00

HAL9000 added this to the v3.7.0 milestone