Implement /new command to start a new conversation (#325)

* Implement /new command to start a new conversation

This adds the /new command which allows users to start a new conversation
from within the CLI without having to close and reopen it.

The /new command:
- Clears all dynamically added widgets from the main display
- Generates a new conversation ID
- Resets the conversation runner
- Updates the splash screen with the new conversation ID
- Shows a notification confirming the new conversation started

If a conversation is currently running, the command shows a warning
and does not proceed.

Fixes #324

Co-authored-by: openhands <openhands@all-hands.dev>

* Change /new command error severity from warning to error

Co-authored-by: openhands <openhands@all-hands.dev>

* Refactor: Extract get_conversation_text utility function

Extract the conversation text formatting logic into a shared utility
function get_conversation_text() in splash.py. This function is now
used by both get_splash_content() and _handle_new_command() to ensure
consistent formatting of the conversation initialization message.

This addresses the code review feedback about sharing implementation
between the /new command and the actual initialization code.

---------

Co-authored-by: openhands <openhands@all-hands.dev>

Author: malhotra5

openhands_cli/tui/content/splash.py

@@ -5,6 +5,19 @@
 from openhands_cli.version_check import check_for_updates
 
 
+def get_conversation_text(conversation_id: str, *, theme: Theme) -> str:
+    """Get the formatted conversation initialization text.
+
+    Args:
+        conversation_id: The conversation ID to display
+        theme: Theme to use for colors
+
+    Returns:
+        Formatted string with conversation initialization message
+    """
+    return f"[{theme.accent}]Initialized conversation[/] {conversation_id}"
+
+
 def get_openhands_banner() -> str:
     """Get the OpenHands ASCII art banner."""
     # ASCII art with consistent line lengths for proper alignment
@@ -35,7 +48,6 @@ def get_splash_content(conversation_id: str, *, theme: Theme) -> dict:
     """
     # Use theme colors
     primary_color = theme.primary
-    accent_color = theme.accent
 
     # Use Rich markup for colored banner (apply color to each line)
     banner_lines = get_openhands_banner().split("\n")
@@ -50,9 +62,7 @@ def get_splash_content(conversation_id: str, *, theme: Theme) -> dict:
         "banner": banner,
         "version": f"OpenHands CLI v{version_info.current_version}",
         "status_text": "All set up!",
-        "conversation_text": (
-            f"[{accent_color}]Initialized conversation[/] {conversation_id}"
-        ),
+        "conversation_text": get_conversation_text(conversation_id, theme=theme),
         "conversation_id": conversation_id,
         "instructions_header": f"[{primary_color}]What do you want to build?[/]",
         "instructions": [

openhands_cli/tui/core/commands.py

@@ -14,6 +14,7 @@
 # Available commands with descriptions after the command
 COMMANDS = [
     DropdownItem(main="/help - Display available commands"),
+    DropdownItem(main="/new - Start a new conversation"),
     DropdownItem(main="/confirm - Configure confirmation settings"),
     DropdownItem(main="/condense - Condense conversation history"),
     DropdownItem(main="/feedback - Send anonymous feedback about CLI"),
@@ -65,6 +66,7 @@ def show_help(main_display: VerticalScroll) -> None:
 [dim]Available commands:[/dim]
 
   [{secondary}]/help[/{secondary}] - Display available commands
+  [{secondary}]/new[/{secondary}] - Start a new conversation
   [{secondary}]/confirm[/{secondary}] - Configure confirmation settings
   [{secondary}]/condense[/{secondary}] - Condense conversation history
   [{secondary}]/feedback[/{secondary}] - Send anonymous feedback about CLI

openhands_cli/tui/textual_app.py

@@ -30,7 +30,7 @@
 )
 from openhands.sdk.security.risk import SecurityRisk
 from openhands_cli.theme import OPENHANDS_THEME
-from openhands_cli.tui.content.splash import get_splash_content
+from openhands_cli.tui.content.splash import get_conversation_text, get_splash_content
 from openhands_cli.tui.core.commands import is_valid_command, show_help
 from openhands_cli.tui.core.conversation_runner import ConversationRunner
 from openhands_cli.tui.modals import SettingsScreen
@@ -422,6 +422,8 @@ def _handle_command(self, command: str) -> None:
 
         if command == "/help":
             show_help(self.main_display)
+        elif command == "/new":
+            self._handle_new_command()
         elif command == "/confirm":
             self._handle_confirm_command()
         elif command == "/condense":
@@ -666,6 +668,59 @@ def _handle_feedback_command(self) -> None:
             severity="information",
         )
 
+    def _handle_new_command(self) -> None:
+        """Handle the /new command to start a new conversation.
+
+        This clears the terminal UI and starts a fresh conversation runner.
+        """
+        # Check if a conversation is currently running
+        if self.conversation_runner and self.conversation_runner.is_running:
+            self.notify(
+                title="New Conversation Error",
+                message="Cannot start a new conversation while one is running. "
+                "Please wait for the current conversation to complete or pause it.",
+                severity="error",
+            )
+            return
+
+        # Generate a new conversation ID
+        self.conversation_id = uuid.uuid4()
+
+        # Reset the conversation runner
+        self.conversation_runner = None
+
+        # Remove any existing confirmation panel
+        if self.confirmation_panel:
+            self.confirmation_panel.remove()
+            self.confirmation_panel = None
+
+        # Clear all dynamically added widgets from main_display
+        # Keep only the splash widgets (those with IDs starting with "splash_")
+        widgets_to_remove = []
+        for widget in self.main_display.children:
+            widget_id = widget.id or ""
+            if not widget_id.startswith("splash_"):
+                widgets_to_remove.append(widget)
+
+        for widget in widgets_to_remove:
+            widget.remove()
+
+        # Update the splash conversation widget with the new conversation ID
+        splash_conversation = self.query_one("#splash_conversation", Static)
+        splash_conversation.update(
+            get_conversation_text(self.conversation_id.hex, theme=OPENHANDS_THEME)
+        )
+
+        # Scroll to top to show the splash screen
+        self.main_display.scroll_home(animate=False)
+
+        # Notify user
+        self.notify(
+            title="New Conversation",
+            message="Started a new conversation",
+            severity="information",
+        )
+
     def _handle_confirmation_request(
         self, pending_actions: list[ActionEvent]
     ) -> UserConfirmation:

tests/tui/test_commands.py

@@ -23,7 +23,7 @@ class TestCommands:
     def test_commands_list_structure(self):
         """Test that COMMANDS list has correct structure."""
         assert isinstance(COMMANDS, list)
-        assert len(COMMANDS) == 5
+        assert len(COMMANDS) == 6
 
         # Check that all items are DropdownItems
         for command in COMMANDS:
@@ -36,6 +36,7 @@ def test_commands_list_structure(self):
         "expected_command,expected_description",
         [
             ("/help", "Display available commands"),
+            ("/new", "Start a new conversation"),
             ("/confirm", "Configure confirmation settings"),
             ("/condense", "Condense conversation history"),
             ("/feedback", "Send anonymous feedback about CLI"),
@@ -72,11 +73,13 @@ def test_show_help_function_signature(self):
         [
             "OpenHands CLI Help",
             "/help",
+            "/new",
             "/confirm",
             "/condense",
             "/feedback",
             "/exit",
             "Display available commands",
+            "Start a new conversation",
             "Configure confirmation settings",
             "Condense conversation history",
             "Send anonymous feedback about CLI",
@@ -145,6 +148,7 @@ def test_show_help_formatting(self):
         "cmd,expected",
         [
             ("/help", True),
+            ("/new", True),
             ("/confirm", True),
             ("/condense", True),
             ("/feedback", True),
@@ -426,3 +430,154 @@ async def test_feedback_command_opens_browser(
                     message="Opening feedback form in your browser...",
                     severity="information",
                 )
+
+    @pytest.mark.asyncio
+    async def test_new_command_starts_new_conversation(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """`/new` should start a new conversation with a new ID."""
+        monkeypatch.setattr(
+            SettingsScreen,
+            "is_initial_setup_required",
+            lambda: False,
+        )
+
+        app = OpenHandsApp(exit_confirmation=False)
+
+        async with app.run_test() as pilot:
+            oh_app = cast(OpenHandsApp, pilot.app)
+
+            # Store the original conversation ID
+            original_conversation_id = oh_app.conversation_id
+
+            # Mock notify to verify notification is shown
+            notify_mock = mock.MagicMock()
+            oh_app.notify = notify_mock
+
+            oh_app._handle_command("/new")
+
+            # Verify a new conversation ID was generated
+            assert oh_app.conversation_id != original_conversation_id
+
+            # Verify conversation runner was reset
+            assert oh_app.conversation_runner is None
+
+            # Verify notification was shown
+            notify_mock.assert_called_once_with(
+                title="New Conversation",
+                message="Started a new conversation",
+                severity="information",
+            )
+
+    @pytest.mark.asyncio
+    async def test_new_command_blocked_when_conversation_running(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """`/new` should show warning when a conversation is running."""
+        monkeypatch.setattr(
+            SettingsScreen,
+            "is_initial_setup_required",
+            lambda: False,
+        )
+
+        app = OpenHandsApp(exit_confirmation=False)
+
+        async with app.run_test() as pilot:
+            oh_app = cast(OpenHandsApp, pilot.app)
+
+            # Create a mock conversation runner that is running
+            dummy_runner = mock.MagicMock()
+            dummy_runner.is_running = True
+            oh_app.conversation_runner = dummy_runner
+
+            # Store the original conversation ID
+            original_conversation_id = oh_app.conversation_id
+
+            # Mock notify to verify warning is shown
+            notify_mock = mock.MagicMock()
+            oh_app.notify = notify_mock
+
+            oh_app._handle_command("/new")
+
+            # Verify conversation ID was NOT changed
+            assert oh_app.conversation_id == original_conversation_id
+
+            # Verify error notification was shown
+            notify_mock.assert_called_once()
+            call_args = notify_mock.call_args
+            assert call_args[1]["title"] == "New Conversation Error"
+            assert call_args[1]["severity"] == "error"
+
+    @pytest.mark.asyncio
+    async def test_new_command_clears_dynamically_added_widgets(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """`/new` should clear dynamically added widgets but keep splash widgets."""
+        from textual.widgets import Static
+
+        monkeypatch.setattr(
+            SettingsScreen,
+            "is_initial_setup_required",
+            lambda: False,
+        )
+
+        app = OpenHandsApp(exit_confirmation=False)
+
+        async with app.run_test() as pilot:
+            oh_app = cast(OpenHandsApp, pilot.app)
+
+            # Add a dynamic widget to main_display (simulating conversation content)
+            dynamic_widget = Static("Test message", classes="user-message")
+            oh_app.main_display.mount(dynamic_widget)
+            await pilot.pause()
+
+            # Verify the widget was added
+            assert dynamic_widget in oh_app.main_display.children
+
+            # Mock notify
+            notify_mock = mock.MagicMock()
+            oh_app.notify = notify_mock
+
+            oh_app._handle_command("/new")
+            await pilot.pause()
+
+            # Verify dynamic widget was removed
+            assert dynamic_widget not in oh_app.main_display.children
+
+            # Verify splash widgets still exist
+            splash_banner = oh_app.query_one("#splash_banner", Static)
+            assert splash_banner is not None
+
+    @pytest.mark.asyncio
+    async def test_new_command_updates_splash_conversation_id(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """`/new` should update the splash conversation widget with new ID."""
+        from textual.widgets import Static
+
+        monkeypatch.setattr(
+            SettingsScreen,
+            "is_initial_setup_required",
+            lambda: False,
+        )
+
+        app = OpenHandsApp(exit_confirmation=False)
+
+        async with app.run_test() as pilot:
+            oh_app = cast(OpenHandsApp, pilot.app)
+
+            # Mock notify
+            notify_mock = mock.MagicMock()
+            oh_app.notify = notify_mock
+
+            oh_app._handle_command("/new")
+            await pilot.pause()
+
+            # Verify splash conversation widget contains the new conversation ID
+            splash_conversation = oh_app.query_one("#splash_conversation", Static)
+            # The content should contain the new conversation ID hex
+            assert oh_app.conversation_id.hex in str(splash_conversation.content)