================================================================================
j-cli CODEBASE ANALYSIS - COMPREHENSIVE SUMMARY
================================================================================

Generated: 2026-04-03
Focus: src/command/chat/ module

================================================================================
1. AUTO_COMPACT FUNCTION CALLS
================================================================================

DEFINITION:
  File: src/command/chat/compact.rs
  Lines: 174-246
  Function: pub async fn auto_compact(messages: &mut Vec<ChatMessage>, provider: &ModelProvider) -> Result<(), String>

TRIGGERED BY (4 locations in agent.rs):

  [1] Line 53 - Main agent loop token threshold check
      Location: src/command/chat/agent.rs:46-56
      Trigger: if compact::estimate_tokens(&messages) > compact_config.token_threshold
      What: Checks if total conversation exceeds 204,800 tokens
      
  [2] Line 319 - After tool execution (non-stream fallback mode)
      Location: src/command/chat/agent.rs:316-320
      Trigger: if compact_requested && compact_config.enabled
      What: Compact tool explicitly called by LLM
      
  [3] Line 402 - After tool execution (stream mode)
      Location: src/command/chat/agent.rs:399-403
      Trigger: if compact_requested && compact_config.enabled
      What: Compact tool explicitly called by LLM
      
  [4] Line 452 - After tool execution (non-stream mode)
      Location: src/command/chat/agent.rs:449-453
      Trigger: if compact_requested && compact_config.enabled
      What: Compact tool explicitly called by LLM

WHAT IT DOES:
  1. Calls save_transcript() → saves all messages to .transcripts/{timestamp}.jsonl
  2. Truncates conversation to 80,000 chars
  3. Calls LLM (non-streaming) to summarize with max_tokens=20,000
  4. Replaces entire messages vector with:
     - One user message: "[Conversation compressed. Transcript: {path}]\n\n{summary}"
     - One assistant message: "Understood. I have the context from the summary. Continuing."

CONFIGURATION (compact.rs:18-54):
  - enabled: true (default)
  - token_threshold: 256 * 800 = 204,800 tokens
  - keep_recent: 10 (tools to preserve in micro_compact)

GRACEFUL DEGRADATION:
  - If LLM call fails → error logged, Err() returned
  - Agent loop continues with original messages
  - No disruption to conversation flow

================================================================================
2. TOAST NOTIFICATION SYSTEM
================================================================================

DATA STRUCTURE (app.rs:138-139):
  pub toast: Option<(String, bool, std::time::Instant)>
  └─ (message, is_error, creation_time)

DISPLAYING TOASTS (app.rs:2633-2635):
  pub fn show_toast(&mut self, msg: impl Into<String>, is_error: bool) {
      self.ui.toast = Some((msg.into(), is_error, std::time::Instant::now()));
  }
  
  Usage:
    app.show_toast("Operation successful", false);  // Green toast ☑️
    app.show_toast("Error occurred", true);         // Red toast ✖️

CLEARING TOASTS (app.rs:2715-2721):
  pub fn tick_toast(&mut self) {
      if let Some((_, _, created)) = &self.ui.toast
          && created.elapsed().as_secs() >= TOAST_DURATION_SECS
      {
          self.ui.toast = None;
      }
  }
  
  Duration: 4 seconds (src/constants.rs:57)
  Called: Each frame in TUI loop (src/command/chat/handler/tui_loop.rs:259)

RENDERING TOASTS (ui/chat.rs:882-926):
  pub fn draw_toast(f: &mut ratatui::Frame, area: Rect, app: &ChatApp)
  
  Position: Top-right corner
    - x offset: area.width - toast_width - 1
    - y offset: 1 from top
  
  Styling:
    - Success: ☑️ with green border/text (theme.toast_success_*)
    - Error: ✖️ with red border/text (theme.toast_error_*)
  
  Layout:
    - Width: calculated from text width, min 16 chars, max screen width
    - Height: fixed 3 rows
    - Border: rounded box (ratatui BorderType::Rounded)

VISUAL APPEARANCE:
  ┌─────────────────────┐
  │ ☑️ Message saved    │
  └─────────────────────┘
        (top-right corner, 4 seconds)

================================================================================
3. TITLE BAR LOADING STATUS
================================================================================

LOCATION: src/command/chat/ui/chat.rs:83-150+

FUNCTION: pub fn draw_title_bar(f: &mut ratatui::Frame, area: Rect, app: &ChatApp)

FORMAT:
  🦞 Sprite  │  💫  {model_name}  │  📬  {msg_count} 条消息  {loading_info}  │  📱 远程已连接

LOADING STATUS LOGIC (lines 87-109):
  
  if app.state.is_loading {
    Priority 1: Find tool in Executing status
      └─ Display: " 🔧 执行 {tool_name}..."
    
    Priority 2: Find tool in PendingConfirm status
      └─ Display: " 🔧 调用 {tool_name}..."
    
    Fallback: No active tools
      └─ Display: " ⏳ 思考中..."
  } else {
    Display: (empty string)
  }

IS_LOADING FLAG (app.rs:259-260):
  pub struct ChatState {
      pub is_loading: bool,  // True while waiting for agent response
  }

ACTIVE TOOL CALLS SOURCE (app.rs:276):
  pub struct ToolExecutor {
      pub active_tool_calls: Vec<ToolCallStatus>,
  }
  
  Each tool has:
    - tool_call_id: String
    - tool_name: String (e.g., "bash", "file_edit")
    - arguments: String
    - confirm_message: String
    - status: ToolExecStatus (PendingConfirm, Executing, Done, Failed, Rejected)

ICON AND COLOR:
  - Icon: 🔧 for tools, ⏳ for thinking
  - Color: theme.title_loading (usually cyan or green)
  - Modifier: BOLD

================================================================================
4. TOOLEXECSTATUS ENUM AND STATES
================================================================================

DEFINITION (app.rs:44-57):
  pub enum ToolExecStatus {
      PendingConfirm,           // Awaiting user confirmation
      Executing,                // Tool is running
      Done(String),             // Completed (summary stored in String)
      Rejected,                 // User refused execution
      Failed(String),           // Execution error (error msg in String)
  }

TRANSITIONS:
  
  PendingConfirm
      ├─ (User allows)    → Executing
      ├─ (User refuses)   → Rejected
      ├─ (Timeout ~10s)   → Executing (auto-execute)
      └─ (Unknown)        → (reserved)
  
  Executing
      ├─ (Tool succeeds)  → Done(summary)
      ├─ (Tool fails)     → Failed(error_msg)
      └─ (User cancels)   → Rejected
  
  Terminal states: Done, Failed, Rejected

TOOLCALLSTATUS STRUCT (app.rs:60-66):
  pub struct ToolCallStatus {
      pub tool_call_id: String,
      pub tool_name: String,
      pub arguments: String,
      pub confirm_message: String,
      pub status: ToolExecStatus,
  }

TOOLEXECUTOR STRUCT (app.rs:274-293):
  pub struct ToolExecutor {
      pub active_tool_calls: Vec<ToolCallStatus>,           // Current tools
      pub pending_tool_idx: usize,                          // Index in ToolConfirm
      pub tool_confirm_entered_at: std::time::Instant,      // For timeout
      pub pending_tool_execution: bool,                     // Execution pending
      pub tools_executing_count: usize,                     // Running count
      pub tool_cancelled: Arc<std::sync::atomic::AtomicBool>,
      pub tool_exec_tx: Option<mpsc::Sender<ToolExecDoneMsg>>,
      pub tool_exec_rx: Option<mpsc::Receiver<ToolExecDoneMsg>>,
      pub tool_result_tx: Option<mpsc::SyncSender<ToolResultMsg>>,
  }

================================================================================
5. TOOL CALLS RENDERING IN MESSAGES
================================================================================

MAIN RENDERING FLOW (render_cache.rs:50-61):
  pub fn build_message_lines_incremental(
      app: &ChatApp,
      inner_width: usize,
      bubble_max_width: usize,
      old_cache: Option<&MsgLinesCache>,
  ) -> (...)
  
  For each message in session.messages:
    - if role="assistant" && has tool_calls
      └─ Call render_tool_call_request_msg() [line 1038]
    
    - if role="tool"
      └─ Call render_tool_result_msg() [line 1165]
    
    - if mode=ToolConfirm
      └─ Call render_tool_confirm_area() [line 577]

TOOL CALL REQUEST RENDERING (render_cache.rs:1038-1120):
  pub fn render_tool_call_request_msg(
      tool_calls: &[super::storage::ToolCallItem],
      bubble_max_width: usize,
      lines: &mut Vec<Line<'static>>,
      theme: &Theme,
      expand: bool,
  )
  
  EXPANDED MODE (expand=true, Ctrl+O toggle):
    - Line 1: icon + name + status_icon
      └─ Example: "  🔧 Bash ⏳"
    - Lines 2+: Parameter details (JSON formatted)
      └─ Example: "    command: ls -la"
               "    cwd: /home/user"
    - Blank line between tools
  
  COLLAPSED MODE (expand=false):
    - Single line per tool: icon + name + 60-char preview
      └─ Example: "  🔧 Bash ls -la /home/user /var/lo…"

TOOL RESULT RENDERING (render_cache.rs:1165-1237):
  pub fn render_tool_result_msg(
      content: &str,
      label: &str,
      bubble_max_width: usize,
      lines: &mut Vec<Line<'static>>,
      theme: &Theme,
      expand: bool,
  )
  
  ALWAYS SHOWS:
    - Line 1: "  🔧 {tool_name} {status_icon} {summary}"
      └─ status_icon: ✓ (success) or ✗ (error)
      └─ summary: First 60 chars or "Success" / "Error: {error}"
  
  EXPANDED MODE (expand=true):
    - Lines 2+: Full output (indented 6 spaces)
    - Error results: Show first 20 lines with red styling
    - Sanitizes ANSI codes and special chars
  
  COLLAPSED MODE (expand=false):
    - Line 1 only (summary truncated)

MESSAGE STORAGE (storage.rs):
  pub struct ChatMessage {
      pub role: String,  // "user", "assistant", "tool", "system"
      pub content: String,
      pub tool_calls: Option<Vec<ToolCallItem>>,  // For role="assistant"
      pub tool_call_id: Option<String>,           // For role="tool"
      pub images: Option<Vec<(u32, u32, Vec<u8>)>>,
  }
  
  pub struct ToolCallItem {
      pub id: String,            // UUID
      pub name: String,          // Tool name
      pub arguments: String,     // JSON
  }

RENDERING HIERARCHY:
  
  Message with tool_calls (role="assistant")
    └─ render_tool_call_request_msg()
       └─ Display tool icons, names, parameters
  
  Message with tool_call_id (role="tool")
    └─ Lookup tool_name from previous assistant message
    └─ render_tool_result_msg()
       └─ Display tool results with success/error status

EXPAND_TOOLS TOGGLE:
  File: app.rs, line 233
  pub expand_tools: bool
  Toggled by: Ctrl+O in TUI
  Affects: All subsequent renders of tool calls/results

================================================================================
6. KEY FILES AND LINE NUMBERS REFERENCE
================================================================================

COMPACTION:
  ✓ auto_compact() definition          src/command/chat/compact.rs:174
  ✓ auto_compact calls                 src/command/chat/agent.rs:53,319,402,452
  ✓ micro_compact()                    src/command/chat/compact.rs:65
  ✓ CompactConfig struct               src/command/chat/compact.rs:18
  ✓ Token threshold calculation        src/command/chat/compact.rs:38-39
  ✓ save_transcript()                  src/command/chat/compact.rs:130

TOAST SYSTEM:
  ✓ Toast field in UIState             src/command/chat/app.rs:138-139
  ✓ show_toast() method                src/command/chat/app.rs:2633
  ✓ tick_toast() method                src/command/chat/app.rs:2715
  ✓ draw_toast() function              src/command/chat/ui/chat.rs:882
  ✓ TOAST_DURATION_SECS constant       src/constants.rs:57
  ✓ Toast polling in loop              src/command/chat/handler/tui_loop.rs:259

TITLE BAR & LOADING:
  ✓ draw_title_bar() function          src/command/chat/ui/chat.rs:83
  ✓ Tool status logic                  src/command/chat/ui/chat.rs:87-109
  ✓ is_loading flag                    src/command/chat/app.rs:259-260
  ✓ Title bar rendering                src/command/chat/ui/chat.rs:111-137

TOOL STATUS:
  ✓ ToolExecStatus enum                src/command/chat/app.rs:44-57
  ✓ ToolCallStatus struct              src/command/chat/app.rs:60-66
  ✓ ToolExecutor struct                src/command/chat/app.rs:274-293
  ✓ active_tool_calls field            src/command/chat/app.rs:276
  ✓ poll_results() method              src/command/chat/app.rs:312
  ✓ execute_batch() method             src/command/chat/app.rs:395

TOOL RENDERING:
  ✓ build_message_lines_incremental()  src/command/chat/render_cache.rs:50
  ✓ Tool call request rendering        src/command/chat/render_cache.rs:135
  ✓ Tool result rendering              src/command/chat/render_cache.rs:177
  ✓ render_tool_call_request_msg()     src/command/chat/render_cache.rs:1038
  ✓ render_tool_result_msg()           src/command/chat/render_cache.rs:1165
  ✓ render_tool_confirm_area()         src/command/chat/render_cache.rs:577

================================================================================
7. CONFIGURATION CONSTANTS
================================================================================

COMPACTION:
  Token Threshold: 256 * 800 = 204,800 tokens
  Micro-compact threshold: 800 bytes
  Keep recent tool results: 10
  Max summary tokens: 20,000

TOAST:
  Duration: 4 seconds
  Position: Top-right corner (x: screen_width - width - 1, y: 1)
  Min width: 16 characters
  Height: 3 rows

TOOL EXECUTION:
  Max tool rounds per request: 10
  Tool confirm timeout: ~10 seconds (auto-execute)
  Tool categories: Various (bash, file_edit, etc.)

================================================================================
8. QUICK DEBUG COMMANDS
================================================================================

Find all auto_compact calls:
  $ grep -n "auto_compact" src/command/chat/agent.rs
  Output: Lines 53, 319, 402, 452

Find toast usage:
  $ grep -n "show_toast\|\.toast\s*=" src/command/chat/app.rs
  Output: Lines 2634 (set), 2719 (clear)

Find tool rendering:
  $ grep -n "render_tool\|ToolExecStatus" src/command/chat/render_cache.rs
  Output: Multiple lines with rendering logic

Check loading flag usage:
  $ grep -n "is_loading" src/command/chat/ui/chat.rs
  Output: Lines where loading status is checked

================================================================================
DOCUMENT FILES CREATED
================================================================================

1. j_cli_analysis.md
   - Comprehensive technical analysis
   - ~14 KB, detailed explanations
   - Best for understanding architecture

2. j_cli_quick_reference.md
   - Quick lookup guide
   - ~9.5 KB, condensed format
   - Best for quick answers

3. J_CLI_VISUAL_GUIDE.md
   - ASCII diagrams and flowcharts
   - Data flow visualization
   - State machine diagrams
   - UI rendering stack diagrams

4. ANALYSIS_SUMMARY.txt
   - This file
   - Complete indexed reference
   - Best for searching specific items

All files located in: /Users/jacklingo/dev_custom/j/

================================================================================
END OF SUMMARY
================================================================================
