From 54f6b4b40ded10cde87a1e20389990b2b8bf38dc Mon Sep 17 00:00:00 2001 From: Mai Development Date: Mon, 26 Jan 2026 22:51:49 -0500 Subject: [PATCH] docs(06): create gap closure plans for CLI interface issues Phase 06: CLI Interface Gap Closure - 2 plans addressing 3 UAT-identified issues - Session persistence: Add missing set_conversation_history method - Session feedback: Add verbose messaging for session file operations - Resource display: Fix color coding with force_terminal=True - Ready for execution to close CLI interface gaps --- .../phases/06-cli-interface/06-05-PLAN.md | 116 +++++++++++++++ .../phases/06-cli-interface/06-06-PLAN.md | 133 ++++++++++++++++++ .planning/phases/06-cli-interface/06-UAT.md | 102 ++++++++++++++ 3 files changed, 351 insertions(+) create mode 100644 .planning/phases/06-cli-interface/06-05-PLAN.md create mode 100644 .planning/phases/06-cli-interface/06-06-PLAN.md create mode 100644 .planning/phases/06-cli-interface/06-UAT.md diff --git a/.planning/phases/06-cli-interface/06-05-PLAN.md b/.planning/phases/06-cli-interface/06-05-PLAN.md new file mode 100644 index 0000000..fd61ed7 --- /dev/null +++ b/.planning/phases/06-cli-interface/06-05-PLAN.md @@ -0,0 +1,116 @@ +--- +phase: 06-cli-interface +plan: 05 +type: execute +wave: 1 +depends_on: [06-02] +files_modified: [src/mai/conversation/state.py] +autonomous: true +gap_closure: true + +must_haves: + truths: + - "Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed" + artifacts: + - path: "src/mai/conversation/state.py" + provides: "ConversationState class with session history management" + contains: "set_conversation_history method" + key_links: + - from: "src/mai/conversation/state.py" + to: "session restoration" + via: "set_conversation_history method converts Ollama messages to ConversationTurn objects" + pattern: "def set_conversation_history" +--- + + +Fix session persistence by adding missing set_conversation_history method to ConversationState class + +Purpose: Resolve the "ConversationState object has no attribute 'set_conversation_history'" error that prevents session restoration from working properly +Output: Working session persistence with contextual recovery messages + + + +@~/.opencode/get-shit-done/workflows/execute-plan.md +@~/.opencode/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +# Gap closure context from UAT +@.planning/phases/06-cli-interface/06-UAT.md + +# Previous session persistence implementation +@.planning/phases/06-cli-interface/06-02-SUMMARY.md + + + + + + Fix ConversationState missing set_conversation_history method + src/mai/conversation/state.py + + Add the missing set_conversation_history method to the ConversationState class: + + 1. Examine the existing ConversationState class structure in src/mai/conversation/state.py + 2. Add set_conversation_history method that: + - Accepts a list of Ollama message dictionaries as input + - Converts each message back to ConversationTurn objects using the existing conversion logic + - Preserves the message order (user then assistant pairs) + - Updates the conversation history and current state appropriately + 3. Ensure the method handles edge cases like empty lists, malformed messages, and None values + 4. Add proper type hints for the method signature + + Reference the existing message conversion logic used when saving sessions to ensure consistent transformation. + + Gap reason: "Missing set_conversation_history method in ConversationState class" + Root cause: Session restoration tries to call this method but it doesn't exist + + + # Test the method exists and works + python -c " +from src.mai.conversation.state import ConversationState +import inspect + +# Check method exists +if hasattr(ConversationState, 'set_conversation_history'): + print('✓ set_conversation_history method exists') + + # Check method signature + sig = inspect.signature(ConversationState.set_conversation_history) + print(f'✓ Method signature: {sig}') +else: + print('✗ set_conversation_history method missing') + exit(1) +" + + + ConversationState class has set_conversation_history method that can convert Ollama messages back to ConversationTurn objects for session restoration + + + + + + +Test session persistence by: +1. Starting a conversation with a few messages +2. Exiting the CLI +3. Restarting the CLI +4. Verifying the welcome message shows time elapsed and conversation history is restored + +Expected: No "ConversationState object has no attribute 'set_conversation_history'" error + + + +- set_conversation_history method exists in ConversationState class +- Method accepts list of Ollama message dictionaries +- Method properly converts messages to ConversationTurn objects +- Session restoration works without AttributeError +- Welcome back message shows correct time elapsed + + + +After completion, create `.planning/phases/06-cli-interface/06-05-SUMMARY.md` + \ No newline at end of file diff --git a/.planning/phases/06-cli-interface/06-06-PLAN.md b/.planning/phases/06-cli-interface/06-06-PLAN.md new file mode 100644 index 0000000..5cde651 --- /dev/null +++ b/.planning/phases/06-cli-interface/06-06-PLAN.md @@ -0,0 +1,133 @@ +--- +phase: 06-cli-interface +plan: 06 +type: execute +wave: 1 +depends_on: [06-02, 06-04] +files_modified: [src/app/__main__.py] +autonomous: true +gap_closure: true + +must_haves: + truths: + - "Messages are automatically saved to ~/.mai/session.json during conversation" + - "Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status" + artifacts: + - path: "src/app/__main__.py" + provides: "CLI with enhanced session feedback and color-coded resource display" + contains: "Console(force_terminal=True), session file feedback messages" + key_links: + - from: "src/app/__main__.py" + to: "session file creation" + via: "Verbose feedback for session operations" + pattern: "session.*created|saved|loaded" + - from: "src/app/__main__.py" + to: "resource display" + via: "Console with force_terminal=True for color support" + pattern: "Console.*force_terminal=True" +--- + + +Enhance CLI user feedback for session operations and fix color-coded resource display + +Purpose: Address two UX issues - users can't see when/where session files are created, and resource monitoring lacks color coding in terminal +Output: CLI with clear session feedback and working color-coded resource monitoring + + + +@~/.opencode/get-shit-done/workflows/execute-plan.md +@~/.opencode/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +# Gap closure context from UAT +@.planning/phases/06-cli-interface/06-UAT.md + +# Previous session persistence and resource monitoring implementations +@.planning/phases/06-cli-interface/06-02-SUMMARY.md +@.planning/phases/06-cli-interface/06-04-SUMMARY.md + + + + + + Add verbose session feedback and fix resource display colors + src/app/__main__.py + + Fix two issues in src/app/__main__.py: + + 1. **Enhance session feedback** - Add user-friendly messaging for session operations: + - When creating new session: "Session created at ~/.mai/session.json" + - When loading existing session: "Session loaded from ~/.mai/session.json" + - When saving session: "Conversation saved to ~/.mai/session.json" + - Enhance /session command to display file path and session stats + - Add feedback for session file creation in ~/.mai directory + + 2. **Fix resource display color coding** - Modify ResourceDisplayManager: + - Change Console initialization to use Console(force_terminal=True) to force color output + - This overrides Rich's automatic terminal detection that disables colors in non-terminal environments + - Ensure rich imports and conditional logic properly handle this change + + Gap reasons: + - "Session system works correctly, but users lack clear feedback about when/where session files are created" + - "Rich console detects is_terminal=False and disables color output automatically" + + Make sure to preserve existing functionality while adding these improvements. + + + # Test session feedback displays file path + echo "Testing session feedback..." && python -c " +import sys +sys.path.insert(0, 'src') +from pathlib import Path +import json + +# Check if session feedback logic exists +with open('src/app/__main__.py', 'r') as f: + content = f.read() + if 'Session created at' in content and 'Session loaded from' in content: + print('✓ Session feedback messages added') + else: + print('✗ Session feedback messages missing') + exit(1) + + # Check for force_terminal=True + if 'force_terminal=True' in content: + print('✓ Console force_terminal=True added') + else: + print('✗ Console force_terminal=True missing') + exit(1) +" + + + CLI now provides clear feedback about session file operations and resource monitoring displays with proper color coding + + + + + + +Test both fixes by: +1. Start new CLI session - should see "Session created at ~/.mai/session.json" +2. Send a message - should see color-coded resource display (not just plain text) +3. Use /session command - should show file location information +4. Exit and restart - should see "Session loaded from ~/.mai/session.json" + +Expected: Clear feedback about session file operations and working color-coded resource monitoring + + + +- Session creation displays file path feedback to user +- Session loading displays file path feedback to user +- /session command shows file information +- Resource monitoring uses color-coded status indicators +- Console initialization uses force_terminal=True for color support + + + +After completion, create `.planning/phases/06-cli-interface/06-06-SUMMARY.md` + \ No newline at end of file diff --git a/.planning/phases/06-cli-interface/06-UAT.md b/.planning/phases/06-cli-interface/06-UAT.md new file mode 100644 index 0000000..ab77d61 --- /dev/null +++ b/.planning/phases/06-cli-interface/06-UAT.md @@ -0,0 +1,102 @@ +--- +status: diagnosed +phase: 06-cli-interface +source: [06-02-SUMMARY.md, 06-04-SUMMARY.md] +started: 2026-01-26T20:00:00Z +updated: 2026-01-26T20:40:00Z +--- + +## Current Test + +[testing complete] + +## Tests + +### 1. Session persistence across restarts +expected: Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed +result: issue +reported: "Welcome back message shows time elapsed but error: 'ConversationState' object has no attribute 'set_conversation_history'" +severity: major + +### 2. Session management commands +expected: Type /session to see session info, /clear to start fresh session +result: pass + +### 3. Conversation history saving +expected: Messages are automatically saved to ~/.mai/session.json during conversation +result: issue +reported: "There is no session.json" +severity: major + +### 4. Large conversation handling +expected: When conversation exceeds 100 messages, older messages are truncated with notification +result: skipped +reason: User chose to skip testing 100 message truncation feature + +### 5. Real-time resource monitoring +expected: Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status +result: issue +reported: "not color coded, but there" +severity: minor + +### 6. Responsive terminal layout +expected: Resource display adapts to terminal width (full/compact/minimal layouts) +result: pass + +### 7. Resource alerts +expected: System shows warnings when resources are constrained (high CPU, low memory) +result: skipped +reason: User chose to skip testing resource constraint warnings + +### 8. Graceful degradation without dependencies +expected: CLI works normally even if rich/blessed packages are missing +result: pass + +## Summary + +total: 8 +passed: 3 +issues: 3 +pending: 0 +skipped: 2 + +## Gaps + +- truth: "Start a conversation, exit CLI, and restart. Session continues with contextual message about time elapsed" + status: failed + reason: "User reported: Welcome back message shows time elapsed but error: 'ConversationState' object has no attribute 'set_conversation_history'" + severity: major + test: 1 + root_cause: "Missing set_conversation_history method in ConversationState class" + artifacts: + - path: "src/mai/conversation/state.py" + issue: "Missing set_conversation_history method" + missing: + - "Add set_conversation_history method to convert Ollama messages back to ConversationTurn objects" + debug_session: ".planning/debug/resolved/session-persistence-error.md" +- truth: "Messages are automatically saved to ~/.mai/session.json during conversation" + status: failed + reason: "User reported: There is no session.json" + severity: major + test: 3 + root_cause: "Session system works correctly, but users lack clear feedback about when/where session files are created" + artifacts: + - path: "src/app/__main__.py" + issue: "Missing user-friendly messaging about session file creation and location" + missing: + - "Add verbose feedback for session operations" + - "Enhance /session command with file information display" + - "Improve new session creation messaging" + debug_session: ".planning/debug/resolved/missing-session-file.md" +- truth: "Resource usage (CPU, RAM, GPU) displays during conversation with color-coded status" + status: failed + reason: "User reported: not color coded, but there" + severity: minor + test: 5 + root_cause: "Rich console detects is_terminal=False and disables color output automatically" + artifacts: + - path: "src/app/__main__.py" + issue: "Console() initialization without force_terminal parameter" + missing: + - "Modify ResourceDisplayManager to use Console(force_terminal=True)" + debug_session: ".planning/debug/resolved/missing-color-coding.md" \ No newline at end of file