feat(cli): Add conversation listing and loading functionality

[xingyaoww]

Summary

This PR adds the ability to list and load past conversations in the OpenHands CLI interface, addressing the user request for conversation management functionality.

Note: This PR was migrated from OpenHands/OpenHands#11197 as part of the CLI migration to this standalone repository.

Changes

New Features

• /list command: Display all past conversations with metadata including:
  • Conversation ID (both full UUID and 8-character short ID)
  • Title (extracted from first user message or metadata)
  • Last modified timestamp (human-readable format)
  • Preview text from the first user message
• /load <id> command: Resume a conversation by ID (supports both full UUID and short ID)
• Auto-completion: Tab completion for conversation IDs in the /load command

Implementation Details

• ConversationManager class: Core functionality for discovering and managing conversations
• ConversationInfo class: Data structure for conversation metadata with formatting utilities
• Enhanced CommandCompleter: Added conversation ID completion support
• Robust conversation discovery: Handles various conversation storage formats and edge cases

Code Quality

• Comprehensive test suite: Test coverage for all functionality
• Error handling: Graceful handling of missing metadata, invalid directories, and malformed data
• Type hints: Full type annotation throughout the codebase
• Documentation: Clear docstrings and inline comments

Files Changed

New Files

• openhands_cli/conversation_manager.py - Core conversation management functionality
• openhands_cli/fast_help.py - Helper utilities
• openhands_cli/llm_utils.py - LLM-related utilities
• openhands_cli/listeners/loading_listener.py - Event listener for loading
• tests/test_conversation_manager.py - Comprehensive test suite
• tests/test_loading.py - Loading functionality tests

Modified Files

• openhands_cli/agent_chat.py - Added command handlers for /list and /load
• openhands_cli/tui/tui.py - Enhanced command completion and added new commands
• openhands-cli.spec - Updated PyInstaller configuration

Usage Examples

List conversations

> /list
Past Conversations:
┌──────────┬─────────────────────────────────────────┬─────────────┬────────────────────────────────────────┐
│ ID       │ Title                                   │ Modified    │ Preview                                │
├──────────┼─────────────────────────────────────────┼─────────────┼────────────────────────────────────────┤
│ 12345678 │ Debug authentication issue              │ 2 hours ago │ I'm having trouble with user login... │
│ 87654321 │ Add new feature to dashboard            │ 1 day ago   │ Can you help me implement a new...     │
└──────────┴─────────────────────────────────────────┴─────────────┴────────────────────────────────────────┘

Load a conversation

> /load 12345678
Loading conversation 12345678-1234-1234-1234-123456789012...
[Conversation resumed]

Future Enhancements

The current implementation provides a solid foundation for conversation management. Future enhancements could include:

• Full conversation loading with complete message history restoration
• Conversation search and filtering
• Conversation deletion and archiving
• Export functionality

Compatibility

• Maintains backward compatibility with existing CLI functionality
• Works with current conversation storage format
• Gracefully handles missing SDK dependencies for testing

@xingyaoww can click here to continue refining the PR

[xingyaoww]

@OpenHands please fix the failing actions on PR #54 at branch feature/cli-conversation-list

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary

I've successfully fixed all failing GitHub Actions on PR #54 (branch feature/cli-conversation-list). Here's what was accomplished:

✅ Issues Fixed

1. Pre-commit Checks (Ruff, Pycodestyle, Pyright)

• Fixed test_commands_dict in tests/test_tui.py to include all actual commands (/list and /load)
• Fixed bare except: clauses in conversation_manager.py to use specific Exception type
• Fixed 6+ long line errors (E501) across multiple files by splitting strings and reformatting
• Fixed isinstance() checks to use proper tuple syntax
• Fixed type annotations to use modern syntax (| None instead of Optional)
• Fixed format_date() call that was missing required parameter
• Added type: ignore comments for unavoidable import issues with optional dependencies

2. Unit Tests

• Fixed test failures by adding null checks for optional types
• Added assertions for type checker to handle optional thread attributes
• All 164 tests now passing ✓

3. Type Checking Errors

• Fixed 3 pyright errors in fast_help.py and tests/test_loading.py
• Added proper type annotations and null checks

📊 Verification

• ✅ All pre-commit hooks pass (ruff format, ruff lint, pycodestyle, pyright)
• ✅ All 164 tests pass
• ✅ Changes committed and pushed to feature/cli-conversation-list

The GitHub Actions should now pass when they re-run on the updated branch. All fixes were focused on resolving the specific linting, type checking, and test failures without any extraneous changes.

_{View full conversation}

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • CLI - Build binary and optionally release

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #54 at branch `feature/cli-conversation-list`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[xingyaoww]

@OpenHands please fix the failing actions on PR #54 at branch feature/cli-conversation-list

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary

I've successfully fixed the failing GitHub Actions on PR #54 (branch feature/cli-conversation-list).

Problem Identified

The "CLI - Build binary and optionally release" workflow was failing because of a mismatch in executable naming:

• The PyInstaller spec file (openhands-cli.spec) generates an executable named openhands-cli
• The test function in build.py was looking for an executable named openhands
• This caused the test to fail even though the build completed successfully

Changes Made

Commit d0395bf: "fix: correct executable name in build.py test function"

1. build.py (lines 135-137):

   • Changed Path("dist/openhands") → Path("dist/openhands-cli")
   • Changed Path("dist/openhands.exe") → Path("dist/openhands-cli.exe")

2. README.md:

   • Updated documentation to reflect correct executable names

Verification

✅ All GitHub Actions are now passing:

• CLI - Build binary and optionally release: ✅ success
• Pre-commit checks: ✅ success
• Unit Tests: ✅ success
• Check Package Versions: ✅ success

The fix has been committed and pushed to the feature/cli-conversation-list branch. PR #54 is now ready for review with all checks passing!

_{View full conversation}