Feat/better session naming

[Boredphilosopher96]

AI-Powered Session Title Generation

Summary

This PR implements intelligent, AI-powered session title generation to improve session discoverability and organization. Instead of relying on timestamps alone, Code Puppy now automatically generates descriptive titles based on the user's first prompt, making it dramatically easier to identify and restore previous sessions.

Problem Statement

Previously, autosaved sessions were identified only by timestamps (e.g., auto_session_20240101_010101), making it difficult for users to:

• Quickly identify what a session was about
• Find specific past conversations
• Understand session context at a glance

Solution

Implemented a lightweight, non-blocking AI title generation system that:

✅ Generates concise titles (≤10 words) based on the user's first meaningful prompt
✅ Falls back gracefully to truncated prompts if AI generation fails
✅ Caches titles to avoid redundant generation
✅ Preserves titles when re-saving existing sessions
✅ Runs asynchronously in a background thread pool to avoid blocking the UI
✅ Maintains backwards compatibility with existing sessions (no breaking changes)

Changes Made

Core Implementation

• Added session_title field to SessionMetadata model with optional typing for backwards compatibility
• Implemented maybe_generate_session_title() function that:
  • Uses a dedicated PydanticAgent with custom instructions
  • Sanitizes and truncates input prompts (max 500 chars)
  • Enforces 10-word maximum on generated titles
  • Caches titles in-memory to prevent duplicate generation
  • Falls back to first 10 words of user prompt if AI generation fails

Integration Points

CLI Interactive Mode (code_puppy/main.py)

• Integrated title generation after first successful agent response
• Only triggers on non-command prompts (filters out / commands)
• Gracefully handles errors without breaking user experience

TUI Mode (code_puppy/tui/app.py)

• Mirrors CLI behavior in the textual user interface
• Displays warnings in chat if title generation fails
• Maintains consistent UX across both modes

Session Display (code_puppy/session_storage.py)

• Updated restore_autosave_interactively() to display titles in session listings
• Format: session_name — title — message_count, saved at timestamp
• Gracefully handles missing titles (backwards compatible)

TUI Session Picker (code_puppy/tui/screens/autosave_picker.py)

• Enhanced AutosaveEntry dataclass with optional session_title field
• Updated _load_metadata() to extract title from metadata JSON
• Updated list item rendering to include titles when available

Session Storage

• Modified save_session() to:
  • Accept optional session_title parameter
  • Retrieve existing titles from metadata if not provided
  • Persist titles to metadata JSON
  • Return title in SessionMetadata object

Configuration Helpers

• Added private module-level caches:

  • _SESSION_FIRST_PROMPT: Tracks first prompt per session
  • _SESSION_TITLE_CACHE: Caches generated titles per session
  • _TITLE_AGENT: Singleton PydanticAgent for title generation
  • _TITLE_THREAD_POOL: ThreadPoolExecutor for async title generation

• Added helper functions:

  • _ensure_title_agent(): Lazy initialization of title generation agent
  • _ensure_title_thread_pool(): Thread pool management
  • _generate_session_title_async(): Async AI title generation
  • _generate_session_title(): Sync wrapper with event loop handling

Technical Details

Design Patterns & Principles

• Lazy Initialization: Title agent and thread pool are only created when needed
• Caching Strategy: Two-level cache (first prompt + generated title) prevents redundant work
• Graceful Degradation: Multiple fallback layers ensure feature never breaks core functionality
• Separation of Concerns: Title generation logic isolated in config.py, not scattered across codebase
• Single Responsibility: Each function has one clear purpose
• Backwards Compatibility: All changes are additive; old sessions load without titles

Thread Safety & Async Handling

• Uses ThreadPoolExecutor to avoid blocking the main event loop
• Properly handles both running and non-running event loops
• Defensive timeout handling (agent configured with retries=1)

AI Agent Configuration

Instructions: "You generate concise session titles based on a user's first prompt. 
               Respond with fewer than ten words, title case preferred, and avoid 
               punctuation beyond spaces."

Constraints:
- Max input: 500 characters (sanitized from user prompt)
- Max output: 10 words (enforced defensively)
- Model: Uses global model configuration
- Retries: 1 (fast-fail for non-critical feature)

Metadata Schema Extension

Before:

{
  "session_name": "auto_session_20240101_010101",
  "message_count": 5,
  "total_tokens": 1234,
  "timestamp": "2024-01-01T00:00:00",
  "auto_saved": true
}

After:

{
  "session_name": "auto_session_20240101_010101",
  "message_count": 5,
  "total_tokens": 1234,
  "timestamp": "2024-01-01T00:00:00",
  "auto_saved": true,
  "session_title": "Implement Session Title Generation"  // NEW
}

Files Modified

File	Changes	Lines
code_puppy/config.py	Added title generation logic, caching, and helper functions	+120
code_puppy/main.py	Integrated title generation in CLI interactive loop	+15
code_puppy/session_storage.py	Enhanced to store/retrieve/display session titles	+35
code_puppy/tui/app.py	Integrated title generation in TUI message handling	+22
code_puppy/tui/screens/autosave_picker.py	Updated picker to display titles in session list	+12
tests/test_session_storage.py	Added tests for title persistence and retrieval	+35
tests/test_auto_save_session.py	Updated test assertions for new metadata field	+2

Key File Changes

code_puppy/config.py

• 📦 Added _SESSION_TITLE_CACHE, _SESSION_FIRST_PROMPT, _TITLE_AGENT, _TITLE_THREAD_POOL module globals
• 🎯 Implemented maybe_generate_session_title() - main public API
• 🔧 Added _ensure_title_agent(), _ensure_title_thread_pool() for resource management
• ⚡ Added _generate_session_title_async(), _generate_session_title() for AI generation
• 🔄 Modified auto_save_session_if_enabled() to include cached titles

code_puppy/session_storage.py

• 📝 Modified save_session() to accept and persist session_title
• 🔍 Added logic to retrieve existing titles from metadata when not provided
• 🖥️ Updated restore_autosave_interactively() to display titles in listings
• 📊 Modified tuple unpacking throughout to handle 4-element tuples (name, ts, count, title)

code_puppy/main.py & code_puppy/tui/app.py

• 🎬 Added post-response hook to trigger title generation
• 🚫 Filters out meta-commands (starting with /)
• ⚠️ Error handling with user-visible warnings in TUI mode

code_puppy/tui/screens/autosave_picker.py

• 🏷️ Extended AutosaveEntry dataclass with session_title field
• 🔄 Updated _load_metadata() to return 3-tuple (timestamp, count, title)
• 🎨 Enhanced list item labels to show name — title — metadata

Testing

New Test Coverage

tests/test_session_storage.py::test_save_session_with_title

• ✅ Verifies title is saved to metadata JSON
• ✅ Confirms title is returned in SessionMetadata object
• ✅ Tests title persistence across multiple saves
• ✅ Validates title retrieval when not explicitly provided

tests/test_auto_save_session.py

• ✅ Updated assertions to expect session_title=None in metadata
• ✅ Ensures backwards compatibility with existing tests

Manual Testing Performed

• ✅ Verified title generation in CLI interactive mode
• ✅ Verified title generation in TUI mode
• ✅ Confirmed graceful fallback when AI generation fails
• ✅ Tested session listing displays with and without titles
• ✅ Validated backwards compatibility with old session files
• ✅ Confirmed title caching prevents redundant generation

Breaking Changes

None. This feature is fully backwards compatible:

• Old sessions without titles continue to work
• session_title field is optional in all contexts
• Title display gracefully handles None values
• No changes to existing session file formats (only additions)

Additional Notes

Performance Considerations

• Title generation runs in background thread pool - zero blocking
• Caching prevents redundant AI calls for the same session
• Fast-fail strategy (1 retry) ensures minimal latency impact
• Fallback to prompt truncation is instantaneous

Future Enhancements

• Add user preference to disable title generation
• Allow manual title editing
• Support regenerating titles for existing sessions
• Add title search/filter in session picker

Code Quality

✅ Follows DRY principles - title logic centralized in config.py
✅ Follows SRP - each function has single, clear responsibility
✅ Follows YAGNI - no speculative features, only what's needed
✅ Type hints on all new functions
✅ Comprehensive docstrings
✅ No files exceed 600 lines

---

Checklist

• Code follows project style guidelines
• Added tests for new functionality
• All tests pass
• No breaking changes
• Documentation updated (inline docstrings)
• Backwards compatible with existing sessions
• Performance impact minimized (async execution)
• Error handling implemented
• Type hints added

Related Issues

Improves user experience for session management and autosave functionality.

[mpfaffenberger]

Nice, I think some different structure may be needed, but I like it!

[mpfaffenberger]

Should this live in side agents/?

[Boredphilosopher96]

To me, having it inside code_puppy folder makes more sense. This is similar to summarization agent than it is to anything inside agents folder. But have moved it out of config per your suggestion

[mpfaffenberger]

I was thinking I need to move that summarizer into the agents namespace

[Boredphilosopher96]

@mpfaffenberger have now moved it to code_puppy folder. Please let me know if it is ok now