indusagi-coding-agent 0.1.22 → 0.1.24

package/dist/modes/interactive/interactive-mode.js

@@ -1,6 +1,167 @@
 /**
- * Interactive mode for the coding agent.
- * Handles TUI rendering and user interaction, delegating business logic to AgentSession.
+ * Interactive Mode - Terminal-based UI for interactive agent use
+ *
+ * ============================================================================
+ * PURPOSE
+ * ============================================================================
+ *
+ * Provides a full-featured terminal UI for interactive use of the coding agent.
+ * Handles rendering, keyboard input, session management, and real-time updates.
+ * This is the primary mode for direct user interaction with the agent.
+ *
+ * ============================================================================
+ * ARCHITECTURE
+ * ============================================================================
+ *
+ * Initialization Phase:
+ * - Create AgentSession with language model and tools
+ * - Load theme system and keyboard bindings
+ * - Initialize TUI (terminal user interface) library
+ * - Set up extension system with UI context
+ * - Load autocomplete provider with fd tool for file paths
+ *
+ * Rendering Phase:
+ * - Terminal layout: Header (logo/changelog) → Chat → Pending → Status → Widgets → Editor → Footer
+ * - Live rendering of agent messages with syntax highlighting
+ * - Real-time tool execution display with collapsible output
+ * - Thinking block display (can be toggled via settings)
+ * - Auto-scrolling to latest message
+ *
+ * Input Phase:
+ * - Keyboard event handling via TUI key system
+ * - Command parsing (/command format)
+ * - Slash command autocomplete with fuzzy filtering
+ * - File path completion via fd tool
+ * - Multi-line editor support with Ctrl+J to continue
+ *
+ * State Management:
+ * - Subscribe to AgentSession events (messages, tools, compaction)
+ * - Update display on each event
+ * - Maintain streaming component state for incremental rendering
+ * - Track tool execution components for expansion control
+ *
+ * ============================================================================
+ * DATA FLOW
+ * ============================================================================
+ *
+ * User Input Flow:
+ *   User Input (keyboard)
+ *     ↓
+ *   TUI Key Handler (in setupKeyHandlers)
+ *     ↓
+ *   Command Parser (parseSlashCommand or plain text)
+ *     ↓
+ *   Command Handler or session.prompt()
+ *     ↓
+ *   AgentSession.prompt() executes agent loop
+ *     ↓
+ *   Agent emits AgentSessionEvent (message, tool, etc.)
+ *     ↓
+ *   Event Subscriber in InteractiveMode (subscribeToAgent)
+ *     ↓
+ *   Display Update (render message, tool, status)
+ *     ↓
+ *   TUI Invalidate → requestRender()
+ *     ↓
+ *   Terminal Output Rendered
+ *
+ * Event Processing Flow:
+ *   agent_start → Show loading animation
+ *   message_streamed → Stream text to AssistantMessageComponent
+ *   tool_call → Create ToolExecutionComponent, show in pending area
+ *   tool_output → Update tool component with result
+ *   message_complete → Move message to chat, hide loading
+ *   compaction_start → Show compaction loader
+ *   compaction_complete → Update with summary message
+ *
+ * ============================================================================
+ * KEY COMPONENTS
+ * ============================================================================
+ *
+ * Renderer:
+ *   - TUI: Core terminal rendering library (from indusagi/tui)
+ *   - Components: Markdown, Text, Container, ProcessTerminal, etc.
+ *   - Handles ANSI codes for colors, styles, and terminal control
+ *   - Manages viewport size and automatic text wrapping
+ *
+ * InputHandler:
+ *   - CustomEditor: Multi-line editor with autocomplete
+ *   - KeybindingsManager: Keyboard shortcut configuration
+ *   - Autocomplete: Slash commands, file paths, templates
+ *   - Command Parser: Processes /settings, /model, /fork, etc.
+ *
+ * DisplayManager:
+ *   - InteractiveMode class: Orchestrates all display updates
+ *   - Container hierarchy: ChatContainer, PendingMessagesContainer, StatusContainer
+ *   - Session display: Shows messages, tools, thinking blocks
+ *   - Component tracking: streamingComponent, pendingTools, etc.
+ *
+ * ThemeManager:
+ *   - Theme system: Colors, styles, layout options
+ *   - EditorTheme: Syntax highlighting for code
+ *   - MarkdownTheme: Rendering options for markdown
+ *   - Theme switching: Hot reload on theme file changes
+ *   - Custom themes: Load from .indusagi/themes/*.json
+ *
+ * Extension System:
+ *   - ExtensionRunner: Manages registered extensions
+ *   - ExtensionUIContext: TUI-based UI for extensions
+ *   - Extension shortcuts: Keyboard shortcuts from extensions
+ *   - Extension widgets: Custom UI above/below editor
+ *   - Extension commands: Custom slash commands
+ *
+ * SessionManager:
+ *   - Session state tracking: Model, messages, tools
+ *   - Session persistence: Save/load from disk
+ *   - Branching: Create branches from previous messages
+ *   - Tree navigation: Switch between branches
+ *
+ * ============================================================================
+ * KEY FEATURES
+ * ============================================================================
+ *
+ * Real-time Streaming:
+ *   - Stream agent responses token-by-token
+ *   - Show tool execution in real-time
+ *   - Display thinking blocks (if enabled)
+ *   - Syntax highlighting for code blocks
+ *
+ * Interactive Commands:
+ *   - /settings: Open settings menu
+ *   - /model: Select language model
+ *   - /fork: Create branch from previous message
+ *   - /tree: Navigate session tree
+ *   - /export: Export to HTML
+ *   - /compact: Manually compact session
+ *   - /new: Start new session
+ *
+ * Session Management:
+ *   - Save/load sessions from disk
+ *   - Branch creation and navigation
+ *   - Automatic context compaction
+ *   - Session switching
+ *
+ * Customization:
+ *   - Custom themes
+ *   - Keyboard bindings
+ *   - Settings (quiet startup, collapse changelog, etc.)
+ *   - Editor options (padding, tab width, etc.)
+ *
+ * ============================================================================
+ * BASED ON INDUSAGI VENDOR
+ * ============================================================================
+ *
+ * This interactive mode implementation is based on indusagi, a terminal UI
+ * toolkit and agent framework maintained at:
+ * https://github.com/varunisrani/indusagi-ts
+ *
+ * Vendor packages used:
+ * - indusagi/tui: Terminal UI components and rendering
+ * - indusagi/ai: AI model interfaces and chat protocol
+ * - indusagi/agent: Core agent session and event system
+ *
+ * Attribution: Builds on proven TUI patterns and architectural decisions
+ * from the original indusagi implementation.
  */
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
@@ -52,6 +213,357 @@ import { getAvailableThemes, getAvailableThemesWithPaths, getEditorTheme, getMar
 function isExpandable(obj) {
     return typeof obj === "object" && obj !== null && "setExpanded" in obj && typeof obj.setExpanded === "function";
 }
+/**
+ * ============================================================================
+ * INTERACTIVE MODE - RENDERING ORCHESTRATION & PIPELINE
+ * ============================================================================
+ *
+ * COMPREHENSIVE RENDERING DOCUMENTATION:
+ * ============================================================================
+ *
+ * This section documents the complete rendering pipeline from session state
+ * to terminal output. The InteractiveMode class manages the TUI layout,
+ * message rendering, and real-time updates for the interactive agent interface.
+ *
+ * RENDERING PIPELINE OVERVIEW:
+ * ============================================================================
+ * End-to-End Flow (from user input to terminal display):
+ *
+ *   User Input (keyboard event)
+ *     ↓
+ *   TUI key handler → setupKeyHandlers()
+ *     ↓
+ *   Command parser (parseSlashCommand or plaintext)
+ *     ↓
+ *   Handler: session.prompt(text) or special command
+ *     ↓
+ *   AgentSession processes (calls LLM, tools, etc.)
+ *     ↓
+ *   Agent emits events: message_streamed, tool_output, etc.
+ *     ↓
+ *   Event handler: subscribeToAgent() listeners
+ *     ↓
+ *   Display update: addMessageToChat() or component.updateResult()
+ *     ↓
+ *   TUI invalidate() → ui.requestRender()
+ *     ↓
+ *   TUI render() → compute layout (width, height, wrapping)
+ *     ↓
+ *   Terminal output: ANSI codes to terminal device
+ *     ↓
+ *   User sees updated chat with new message
+ *
+ * LAYOUT STRUCTURE:
+ * ============================================================================
+ * Terminal Layout (top to bottom):
+ *
+ *   ┌─────────────────────────────────────────────────────┐
+ *   │ [Logo/Changelog] (conditionally shown at startup)   │  1-10 lines
+ *   ├─────────────────────────────────────────────────────┤
+ *   │                                                     │
+ *   │  Chat Messages (scrollable, grows downward)        │  N lines
+ *   │  ├─ User message (background colored)             │
+ *   │  ├─ Assistant message                             │
+ *   │  ├─ Tool execution (pending or complete)          │
+ *   │  └─ ...more messages...                           │
+ *   │                                                     │
+ *   ├─────────────────────────────────────────────────────┤
+ *   │ Pending Messages (tools being executed)            │  1-20 lines
+ *   │ ├─ Tool call (pending background)                 │
+ *   │ └─ ...more pending tools...                       │
+ *   ├─────────────────────────────────────────────────────┤
+ *   │ Status Line (operation status)                     │  1 line
+ *   │ "Thinking..." or "Reading files..." or "Complete" │
+ *   ├─────────────────────────────────────────────────────┤
+ *   │ [Widgets] (optional, from extensions)              │  0-5 lines
+ *   ├─────────────────────────────────────────────────────┤
+ *   │ [Editor] (multi-line input)                        │  3-10 lines
+ *   │ > User typing here...                             │
+ *   │ > Can span multiple lines                         │
+ *   ├─────────────────────────────────────────────────────┤
+ *   │ [Footer] (status, model, etc.)                     │  1 line
+ *   │ Model: GPT-4 | Tokens: 4,251 | Compaction: ...   │
+ *   └─────────────────────────────────────────────────────┘
+ *
+ * Container Hierarchy:
+ *   - mainContainer: Root container for entire UI
+ *     ├── logoContainer: Logo/changelog (conditional)
+ *     ├── chatContainer: All completed messages
+ *     ├── pendingMessagesContainer: Tools being executed
+ *     ├── statusContainer: Status line
+ *     ├── widgetsContainer: Extension widgets
+ *     ├── editorContainer: Multi-line input
+ *     └── footerComponent: Status bar at bottom
+ *
+ * RENDERING MODES:
+ * ============================================================================
+ *
+ * 1. INITIAL LOAD (renderInitialMessages):
+ *    Purpose: Display all messages when session loads
+ *    Process:
+ *      a. Session manager builds aligned message context
+ *      b. Iterate through all messages (oldest to newest)
+ *      c. For each assistant message:
+ *         - Create AssistantMessageComponent
+ *         - For each tool call in message:
+ *           - Create ToolExecutionComponent (no result yet)
+ *           - Render to chatContainer
+ *      d. For each tool result message:
+ *         - Find matching pending tool
+ *         - Call component.updateResult()
+ *         - Remove from pending map
+ *      e. Update footer (token count, context info)
+ *      f. Add user messages to editor history (for Up arrow)
+ *      g. Call ui.requestRender()
+ *
+ * 2. STREAMING UPDATES (handleEvent):
+ *    Purpose: Update display as agent processes real-time
+ *    Process:
+ *      a. Agent emits message_streamed event
+ *      b. Extract message from event.message
+ *      c. Create/update component:
+ *         - First event: Create AssistantMessageComponent
+ *         - Subsequent events: Call component.updateContent()
+ *      d. Add to chatContainer if first event
+ *      e. Update footer status (show operation in progress)
+ *      f. TUI invalidate() and requestRender()
+ *    Optimization:
+ *      - Streaming component cached (one per assistant message)
+ *      - Only call updateContent() on new content (not full rebuild)
+ *      - Markdown rendering is lazy-cached by TUI library
+ *
+ * 3. TOOL EXECUTION (handleEvent + renderSessionContext):
+ *    Purpose: Show tool calls and their results
+ *    Process:
+ *      a. Agent emits message_update (tool call started)
+ *      b. Render tool call with pending background
+ *      c. Tool executes (could take seconds/minutes)
+ *      d. Agent emits tool_output event
+ *      e. Find tool component in pendingTools map
+ *      f. Call component.updateResult()
+ *      g. Pending background changes to success/error
+ *      h. Remove from pendingTools (completed)
+ *      i. User can expand/collapse output via toolOutputExpanded setting
+ *
+ * 4. REAL-TIME BASH (handleBashCommand):
+ *    Purpose: Stream bash output line-by-line
+ *    Process:
+ *      a. User types !! command
+ *      b. Create BashExecutionComponent
+ *      c. Start bash execution (async)
+ *      d. Agent streams stdout chunks
+ *      e. For each chunk:
+ *         - Call component.appendOutput()
+ *         - Component appends to outputLines
+ *         - Call updateDisplay() and requestRender()
+ *      f. When done, call component.setComplete()
+ *      g. Show exit code or cancellation message
+ *
+ * 5. REBUILD (rebuildChatFromMessages):
+ *    Purpose: Clear and re-render after settings change or recovery
+ *    Process:
+ *      a. Clear chatContainer
+ *      b. Call renderInitialMessages()
+ *      c. All messages re-created with new settings
+ *      d. Useful for: thinking block toggle, theme change, etc.
+ *
+ * STYLING & COLOR SCHEME:
+ * ============================================================================
+ * Message Type Colors:
+ *   - User message: userMessageBg + userMessageText (background + text)
+ *   - Assistant: Normal markdown colors (no background)
+ *   - Tool pending: toolPendingBg (neutral during execution)
+ *   - Tool success: toolSuccessBg (green tint after success)
+ *   - Tool error: toolErrorBg (red tint after error)
+ *   - Bash: bashMode color (border + command)
+ *   - Error: theme.fg("error", text) (red)
+ *   - Warning: theme.fg("warning", text) (yellow)
+ *   - Muted: theme.fg("muted", text) (dim/gray)
+ *
+ * Code Highlighting:
+ *   - Markdown: Full markdown with syntax-highlighted code blocks
+ *   - Code inline: Monospace with color
+ *   - Code block: Full syntax highlighting via highlight.js
+ *   - Languages detected from file extensions
+ *   - Theme provides editor theme for highlighting
+ *
+ * Spacing & Layout:
+ *   - Line height: 1 logical line per message (no double spacing)
+ *   - Margins: Spacer(1) before each message type
+ *   - Padding: 1 char left/right within backgrounds
+ *   - Terminal width: Auto-wrap text to terminal width
+ *   - Viewport: Scrollable (auto-scroll to bottom on new message)
+ *
+ * PERFORMANCE CONSIDERATIONS:
+ * ============================================================================
+ *
+ * Streaming Performance:
+ *   - Streaming component cached: Only one active at a time
+ *   - Markdown incremental: TUI library caches rendering
+ *   - Invalidate efficient: Only re-renders changed container
+ *   - Suitable for: 100+ stream updates without lag
+ *
+ * Large Conversations:
+ *   - Tool caching: pendingTools map (fast lookup by ID)
+ *   - Lazy rendering: Messages only rendered when visible
+ *   - No 1000+ message overhead with proper viewport management
+ *   - Compaction system: Auto-summarizes old messages to save memory
+ *
+ * Image Handling:
+ *   - Async conversion: Non-blocking PNG conversion for Kitty protocol
+ *   - Lazy loading: Images loaded when result arrives
+ *   - Format detection: MIME type checked, converted if needed
+ *   - Display control: showImages setting filters images
+ *
+ * Diff Computation:
+ *   - Async preview: Edit diff computed before tool runs
+ *   - Result override: Post-execution diff takes priority
+ *   - Caching: Results cached to avoid re-computation
+ *   - Race handling: File modifications between preview/execution
+ *
+ * INTERACTIVE FEATURES:
+ * ============================================================================
+ *
+ * Keyboard Controls:
+ *   - Enter: Send message
+ *   - Ctrl-J: Continue multi-line message
+ *   - Arrow Up: Recall previous message from history
+ *   - /settings: Open settings dialog
+ *   - /model: Select language model
+ *   - Tab: Autocomplete
+ *   - Ctrl-C: Cancel current operation or exit
+ *
+ * Expandable Elements:
+ *   - Tool output: Expand to see full output (toolOutputExpanded setting)
+ *   - Code blocks: Expand long code to show all lines
+ *   - Tool list: Expand to show all matching tools
+ *   - Bash output: Expand from preview (20 lines) to full
+ *
+ * Real-time Status:
+ *   - Status line: Shows current operation (thinking, reading, writing)
+ *   - Footer: Token count, model name, session info
+ *   - Loader: Animated spinner for long operations
+ *   - Progress: Some operations show progress indicator
+ *
+ * Session Management:
+ *   - Fork: Create branch from previous message
+ *   - Tree: Navigate between branches
+ *   - Save: Auto-save to .indusagi/sessions/
+ *   - Resume: Load previous session on startup
+ *
+ * EXAMPLE RENDERING SEQUENCES:
+ * ============================================================================
+ *
+ * Sequence 1: User Prompt → Assistant Response
+ * ─────────────────────────────────────────────
+ *
+ * 1. User types "read src/main.ts" and presses Enter
+ * 2. CustomEditor captures text and clears
+ * 3. session.prompt(text) called
+ * 4. Agent starts processing
+ * 5. Agent emits message_streamed with assistant message (empty)
+ *    → CreateAssistantMessageComponent, add to chatContainer
+ *    → Show status "Thinking..."
+ * 6. Agent streams text tokens "I'll read the file..."
+ *    → component.updateContent(), add text to message
+ *    → invalidate() and requestRender()
+ * 7. Agent detects tool call (read)
+ *    → Emit message_update with tool call
+ *    → CreateToolExecutionComponent, add to chatContainer
+ *    → pendingTools["id"] = component
+ * 8. Tool executes on server
+ * 9. Agent emits tool_output with result
+ *    → Find component in pendingTools["id"]
+ *    → component.updateResult(result)
+ *    → Remove from pendingTools
+ *    → Background changes from pending to success
+ * 10. Agent completes
+ *    → Hide status line
+ *    → Show footer with token count
+ * 11. Entire sequence rendered to terminal
+ *
+ * Sequence 2: Real-time Bash Output
+ * ──────────────────────────────────
+ *
+ * 1. User types "!!ls -la /src" and presses Enter
+ * 2. handleBashCommand() parses and creates BashExecutionComponent
+ * 3. Component shows header and loader
+ * 4. Shell command starts (async)
+ * 5. Shell outputs "total 128\ndrwx..." chunk 1
+ *    → component.appendOutput(chunk)
+ *    → outputLines = ["total 128", "drwx..."]
+ *    → updateDisplay() and requestRender()
+ * 6. Shell outputs "-rw-r--..." chunk 2
+ *    → component.appendOutput(chunk)
+ *    → outputLines += ["-rw-r--..."]
+ *    → updateDisplay() and requestRender()
+ * 7. Shell outputs "(exit 0)" and completes
+ *    → component.setComplete(0, false, ...)
+ *    → Loader stops, exit code shown
+ *    → updateDisplay() and requestRender()
+ * 8. Final output rendered to terminal
+ *
+ * TERMINAL DIMENSIONS & WRAPPING:
+ * ============================================================================
+ *
+ * Width Handling:
+ *   - Terminal width from ui.terminal.columns
+ *   - TUI library auto-wraps text at this width
+ *   - Code blocks may overflow (user can scroll horizontally)
+ *   - Table rendering respects width (may abbreviate cells)
+ *
+ * Height Handling:
+ *   - Terminal height from ui.terminal.rows
+ *   - mainContainer grows as needed (scrollable)
+ *   - Chat area expands to fill available space
+ *   - Footer always at bottom (fixed)
+ *   - Editor always above footer (fixed)
+ *
+ * Dynamic Resizing:
+ *   - TUI detects terminal resize (SIGWINCH)
+ *   - All components re-render with new dimensions
+ *   - invalidate() called on all containers
+ *   - Visual line truncation recached (width-aware)
+ *   - Auto-scroll adjusted to show latest message
+ *
+ * Text Truncation:
+ *   - Long lines: Wrapped automatically by TUI
+ *   - Visual truncation: truncateToVisualLines() respects width
+ *   - Ellipsis: "..." used to indicate truncation
+ *   - Hints: Show "(to expand)" for cut-off content
+ *
+ * INTEGRATION WITH EXTENSIONS:
+ * ============================================================================
+ *
+ * Custom Renderers:
+ *   - Extension provides renderCall() and renderResult()
+ *   - Called from ToolExecutionComponent.updateDisplay()
+ *   - Custom components rendered within tool box
+ *   - Falls back to built-in rendering if custom fails
+ *
+ * Custom Commands:
+ *   - Extension registers slash command handler
+ *   - Command handler called from InteractiveMode.handleCommand()
+ *   - Can show dialogs, update display, etc.
+ *   - Can access session and TUI for rendering
+ *
+ * Widgets:
+ *   - Extension provides widget component
+ *   - Rendered in widgetsContainer above editor
+ *   - Can show status, buttons, controls, etc.
+ *   - Multiple widgets stack vertically
+ *
+ * SEE ALSO:
+ * ============================================================================
+ * - AssistantMessageComponent: Text/thinking rendering
+ * - UserMessageComponent: User prompt rendering
+ * - ToolExecutionComponent: Tool call/result rendering
+ * - BashExecutionComponent: Real-time bash output
+ * - renderInitialMessages(): Full session rendering
+ * - renderSessionContext(): Message-by-message rendering
+ * - handleEvent(): Real-time event processing
+ * - subscribeToAgent(): Event subscription setup
+ */
 export class InteractiveMode {
     // Convenience accessors
     get agent() {
@@ -114,8 +626,47 @@ export class InteractiveMode {
         // Custom header from extension (undefined = use built-in header)
         this.customHeader = undefined;
         /**
-         * Gracefully shutdown the agent.
-         * Emits shutdown event to extensions, then exits.
+         * Gracefully shutdown the interactive mode and exit.
+         *
+         * PURPOSE:
+         * Clean shutdown sequence. Gives extensions opportunity to clean up,
+         * waits for pending renders, then exits the process.
+         *
+         * PROCESS:
+         * 1. Check if already shutting down (prevent double shutdown)
+         * 2. Emit session_shutdown event to extensions
+         *    - Extensions can clean up resources, save state, etc.
+         *    - Waits for handlers to complete
+         * 3. Wait one tick for pending renders to complete
+         * 4. Call stop() to clean up UI resources:
+         *    a. Stop loading animation
+         *    b. Dispose footer
+         *    c. Unsubscribe from agent events
+         *    d. Stop TUI (restore terminal)
+         * 5. Exit process with code 0
+         *
+         * TRIGGERS:
+         * - User presses Ctrl+D (when editor empty)
+         * - User presses Ctrl+C twice within 500ms
+         * - User enters /quit or /exit
+         * - Extension calls shutdown() via context
+         *
+         * PARAMETERS:
+         * None
+         *
+         * RETURNS:
+         * Promise<void> - never resolves (process.exit is called)
+         *
+         * NOTES:
+         * - Sets this.isShuttingDown flag to prevent double-shutdown
+         * - Emits session_shutdown event (not awaited if no handlers)
+         * - Extensions can catch this event with .on("session_shutdown")
+         * - Clean exits prevent terminal corruption
+         * - TUI stop() restores cursor and clear screen
+         *
+         * SEE ALSO:
+         * - stop() which does actual cleanup
+         * - checkShutdownRequested() which triggers shutdown on agent_end
          */
         this.isShuttingDown = false;
         this.session = session;
@@ -218,6 +769,44 @@ export class InteractiveMode {
     rebuildAutocomplete() {
         this.setupAutocomplete(this.fdPath);
     }
+    /**
+     * Initialize the interactive mode UI and extensions.
+     *
+     * PURPOSE:
+     * Sets up the terminal UI, keyboard handlers, event subscriptions, and extension system.
+     * This prepares the interactive mode for user interaction. Must be called before run().
+     *
+     * PROCESS:
+     * 1. Load changelog entries and check for initial messages
+     * 2. Ensure fd tool is available for file path autocomplete
+     * 3. Build autocomplete provider (slash commands, templates, extensions, skills)
+     * 4. Initialize TUI with header (logo, keybinding hints, changelog)
+     * 5. Add layout components (chat, pending, status, widgets, editor, footer)
+     * 6. Set up keyboard handlers (key bindings, editor events)
+     * 7. Start the TUI (terminal raw mode, enable mouse, etc.)
+     * 8. Initialize extension system with TUI-based UI context
+     * 9. Subscribe to agent events (messages, tools, compaction, retry)
+     * 10. Set up theme file watcher for hot reload
+     * 11. Set up git branch watcher for footer
+     * 12. Initialize available provider count for display
+     *
+     * PARAMETERS:
+     * None - uses constructor options for initial messages and warnings
+     *
+     * RETURNS:
+     * Promise<void> - resolves when initialization is complete
+     *
+     * STATE CHANGES:
+     * - Sets isInitialized flag to true
+     * - Starts TUI (terminal is in raw mode after this)
+     * - Sets terminal title with session name
+     * - Subscribes to agent events and theme changes
+     *
+     * NOTES:
+     * - Must be idempotent (calling twice does nothing on second call)
+     * - Extension system is fully initialized here
+     * - Changelog is only shown for new sessions, not resumed ones
+     */
     async init() {
         if (this.isInitialized)
             return;
@@ -337,8 +926,45 @@ export class InteractiveMode {
         }
     }
     /**
-     * Run the interactive mode. This is the main entry point.
-     * Initializes the UI, shows warnings, processes initial messages, and starts the interactive loop.
+     * Run the interactive mode main loop.
+     *
+     * PURPOSE:
+     * Main entry point for interactive mode. Initializes UI, displays startup info,
+     * processes initial messages, and enters the interactive user input loop.
+     * Never returns under normal operation (runs until user exits with /quit, Ctrl+D, etc.).
+     *
+     * PROCESS:
+     * 1. Call init() to set up UI, keyboard handlers, extensions
+     * 2. Start version check asynchronously (shows notification if newer version available)
+     * 3. Render initial session messages from previous session (if resumed)
+     * 4. Show startup warnings:
+     *    - Migrated provider credentials
+     *    - models.json parsing errors
+     *    - Model fallback message (if model couldn't be restored)
+     * 5. Process initial messages from options (--message, --initial-message):
+     *    - Send each via session.prompt()
+     *    - Catch and display errors
+     * 6. Start interactive loop:
+     *    a. Wait for user input (getUserInput waits for editor.onSubmit)
+     *    b. Send input to session.prompt()
+     *    c. Loop continues until shutdown (process.exit)
+     *
+     * PARAMETERS:
+     * None - uses constructor options for initial messages and warnings
+     *
+     * RETURNS:
+     * Promise<void> - never resolves (runs until process.exit is called)
+     *
+     * STATE CHANGES:
+     * - Initializes all UI components
+     * - Starts the interactive input loop
+     * - Updates footer/display as agent processes messages
+     * - May create new sessions, fork, navigate tree, etc. based on commands
+     *
+     * NOTES:
+     * - Must call init() first
+     * - Handles all errors from session.prompt() and displays them
+     * - Runs forever - shutdown happens via /quit, Ctrl+D, or extension shutdown signal
      */
     async run() {
         await this.init();
@@ -782,6 +1408,63 @@ export class InteractiveMode {
     }
     /**
      * Initialize the extension system with TUI-based UI context.
+     *
+     * PURPOSE:
+     * Set up extensions with UI capabilities. Creates ExtensionUIContext for
+     * extensions to use for dialogs, widgets, status messages, etc.
+     * Binds command context actions, error handlers, and shutdown handler.
+     *
+     * PROCESS:
+     * 1. If no extension runner: show loaded resources and return
+     * 2. Create ExtensionUIContext with:
+     *    a. Dialog methods (select, confirm, input, notify)
+     *    b. Status/title setters
+     *    c. Widget and footer/header setters
+     *    d. Editor interaction methods
+     *    e. Theme access and switching
+     * 3. Call session.bindExtensions() with:
+     *    a. uiContext - for TUI dialogs
+     *    b. commandContextActions - for /fork, /tree, /new actions
+     *    c. shutdownHandler - called when extension wants to exit
+     *    d. Error handlers - for extension and hook errors
+     * 4. Set up extension shortcuts (keyboard bindings from extensions)
+     * 5. Show loaded resources (extensions, skills, prompts, themes)
+     *
+     * EXTENSION CAPABILITIES:
+     * - Show dialogs (selectors, confirmations, inputs)
+     * - Display persistent widgets above/below editor
+     * - Set custom footer and header
+     * - Customize editor component
+     * - Register keyboard shortcuts
+     * - Request shutdown
+     * - Access theme system
+     *
+     * COMMAND CONTEXT ACTIONS:
+     * - waitForIdle(): Wait until agent is idle
+     * - newSession(): Start a new session
+     * - fork(): Create branch from previous message
+     * - navigateTree(): Switch to different point in tree
+     *
+     * PARAMETERS:
+     * None
+     *
+     * RETURNS:
+     * Promise<void> - completes when extensions are initialized
+     *
+     * STATE CHANGES:
+     * - Binds extensions to session
+     * - Sets up shortcuts on defaultEditor
+     * - Displays loaded resources in chat
+     *
+     * NOTES:
+     * - Called from init() after TUI is started
+     * - Extensions can't affect UI until this completes
+     * - Error/hook errors displayed but don't stop initialization
+     * - Resources shown only if verbose or not quietStartup
+     *
+     * SEE ALSO:
+     * - createExtensionUIContext() for UI API details
+     * - setupExtensionShortcuts() for keyboard bindings
      */
     async initExtensions() {
         const extensionRunner = this.session.extensionRunner;
@@ -1428,6 +2111,100 @@ export class InteractiveMode {
     // =========================================================================
     // Key Handlers
     // =========================================================================
+    /**
+     * Set up keyboard event handlers for all key bindings.
+     *
+     * PURPOSE:
+     * Registers all keyboard shortcuts and special key handlers on the editor.
+     * Handles direct key events (Escape, Ctrl+D, etc.) and action dispatching
+     * for keybinding-mapped actions (clear, suspend, cycle models, etc.).
+     *
+     * KEY BINDINGS CONFIGURED:
+     *
+     * **Escape**:
+     * - If loading: restore queued messages and abort agent
+     * - Else if bash running: abort bash
+     * - Else if bash mode (!): clear input and exit bash mode
+     * - Else if editor has text: clear editor
+     * - Else double-escape with empty: open tree selector or fork selector
+     *   (based on settings.doubleEscapeAction)
+     *
+     * **Ctrl+C** (mapped to "clear" action):
+     * - First press: clear editor
+     * - Second press within 500ms: exit application
+     *
+     * **Ctrl+D** (mapped via onCtrlD):
+     * - Only when editor is empty
+     * - Exit application immediately
+     *
+     * **Ctrl+Z** (mapped to "suspend" action):
+     * - Suspend terminal to background
+     * - Set up SIGCONT handler to restore TUI on resume
+     *
+     * **Ctrl+M** (mapped to "cycleThinkingLevel" action):
+     * - Cycle thinking level: off → low → medium → high → off
+     * - Update border color and footer
+     * - Show status message
+     *
+     * **Ctrl+N** (mapped to "cycleModelForward" action):
+     * - Cycle to next model in scope or registry
+     * - Update footer and border color
+     * - Show status with new model name
+     *
+     * **Ctrl+P** (mapped to "cycleModelBackward" action):
+     * - Cycle to previous model
+     *
+     * **Ctrl+L** (mapped to "selectModel" action):
+     * - Open model selector dialog
+     *
+     * **Ctrl+E** (mapped to "expandTools" action):
+     * - Toggle expansion state of all tool output components
+     * - Affects current and future tool displays
+     *
+     * **Ctrl+K** (mapped to "toggleThinking" action):
+     * - Toggle visibility of thinking blocks in all messages
+     * - Rebuild chat with updated visibility
+     *
+     * **Ctrl+X** (mapped to "externalEditor" action):
+     * - Open current editor content in $VISUAL or $EDITOR
+     * - Replace content on save
+     *
+     * **Alt+Enter** (mapped to "followUp" action):
+     * - If streaming: queue message to send after agent finishes
+     * - If idle: acts like regular Enter (trigger onSubmit)
+     *
+     * **Ctrl+J** (mapped to "dequeue" action):
+     * - Restore all queued messages back to editor
+     * - Show count of restored messages
+     *
+     * **Alt+Debug** (global on TUI, not editor):
+     * - Write debug log with terminal render state and agent messages
+     *
+     * **onChange**:
+     * - Track if text starts with ! to enter bash mode
+     * - Update editor border color (blue for bash, accent for thinking)
+     *
+     * **onPasteImage**:
+     * - Handle Ctrl+V clipboard image paste
+     * - Write to temp file, insert path in editor
+     *
+     * PARAMETERS:
+     * None - configures this.defaultEditor handlers
+     *
+     * RETURNS:
+     * void - side effects only
+     *
+     * STATE CHANGES:
+     * - Sets this.defaultEditor.onEscape, onSubmit, onChange, onCtrlD, onPasteImage
+     * - Sets this.defaultEditor action handlers (clear, suspend, etc.)
+     * - Sets this.ui.onDebug for global debug shortcut
+     *
+     * NOTES:
+     * - Handlers use this.editor (which may be custom from extension)
+     * - All handlers use updateEditorBorderColor() to reflect state
+     * - Extension shortcuts can override action handlers via registerShortcut()
+     * - Most handlers call updatePendingMessagesDisplay() to sync UI
+     */
     setupKeyHandlers() {
         // Set up handlers on defaultEditor - they use this.editor for text access
         // so they work correctly regardless of which editor is active
@@ -1511,6 +2288,93 @@ export class InteractiveMode {
             // Silently ignore clipboard errors (may not have permission, etc.)
         }
     }
+    /**
+     * Set up the editor submit handler for user input.
+     *
+     * PURPOSE:
+     * Configures the editor's onSubmit callback to process user input.
+     * This is called when the user presses Enter in the editor.
+     * Handles command parsing, slash commands, bash execution, and message queuing.
+     *
+     * INPUT TYPES PROCESSED:
+     *
+     * **Slash Commands** (commands starting with /):
+     * - /settings: Open settings selector menu
+     * - /scoped-models: Open model scoping selector
+     * - /model [search]: Open model selector or find exact match
+     * - /export [path]: Export session to HTML file
+     * - /share: Share session as secret GitHub gist
+     * - /copy: Copy last agent message to clipboard
+     * - /name [name]: Set or display session name
+     * - /session: Show session info and stats (messages, tokens, cost)
+     * - /changelog: Show full changelog entries
+     * - /hotkeys: Show all keyboard shortcuts
+     * - /fork: Show fork selector (pick message to branch from)
+     * - /tree: Show tree selector (navigate session DAG)
+     * - /login: Open OAuth or API key login selector
+     * - /logout: Open logout selector for saved credentials
+     * - /new, /clear: Start a new session
+     * - /compact [instructions]: Manually compact context
+     * - /reload: Reload extensions, skills, prompts, themes
+     * - /resume: Show session selector to switch sessions
+     * - /quit, /exit: Exit the application
+     *
+     * **Bash Commands** (text starting with ! or !!):
+     * - !command: Execute bash command, include output in context
+     * - !!command: Execute bash command, exclude from context (use !!)
+     * - Shows BashExecutionComponent with real-time output
+     * - Can be queued during streaming (moved to chat on next submit)
+     *
+     * **Prompt Templates** (custom /name commands):
+     * - Registered template names become slash commands
+     * - Can have placeholders and argument completion
+     * - Expanded and sent as regular messages
+     *
+     * **Extension Commands**:
+     * - Custom commands registered by extensions
+     * - Execute immediately even during streaming
+     * - Can provide argument completion
+     *
+     * **Regular Messages**:
+     * - If streaming: queue with streaming behavior (steer/followUp)
+     *   - "steer": interrupt immediately
+     *   - "followUp": wait until response finishes
+     * - If compacting: queue in compactionQueuedMessages
+     * - If idle: send immediately
+     * - Can include @file references for context injection
+     *
+     * COMMAND PARSING:
+     * 1. Trim whitespace
+     * 2. Check if it's a slash command (/command or /command arg)
+     * 3. Check if it's a bash command (!cmd or !!cmd)
+     * 4. Otherwise treat as regular message
+     *
+     * QUEUEING BEHAVIOR:
+     * - During streaming: prompt() with streamingBehavior option
+     * - During compaction: compactionQueuedMessages array
+     * - Queued messages shown in pendingMessagesContainer
+     * - Can be dequeued with Ctrl+J and edited
+     *
+     * PARAMETERS:
+     * @param text - The submitted editor text (trimmed)
+     *
+     * RETURNS:
+     * void - async, calls callbacks but doesn't return a value
+     *
+     * STATE CHANGES:
+     * - Clears editor text on submit
+     * - Adds to editor history (for Up arrow to recall)
+     * - Updates pendingMessagesDisplay when queuing
+     * - Moves pendingBashComponents to chat
+     * - Calls session.prompt() or command handlers
+     *
+     * NOTES:
+     * - Empty input is ignored
+     * - All errors are caught and displayed via showError()
+     * - Some commands suppress editor.addToHistory() (reload, etc.)
+     * - Bash commands check if bash is already running and warn
+     * - Must check isBashMode before allowing bash command execution
+     */
     setupEditorSubmitHandler() {
         this.defaultEditor.onSubmit = async (text) => {
             text = text.trim();
@@ -1672,11 +2536,132 @@ export class InteractiveMode {
             this.editor.addToHistory?.(text);
         };
     }
+    /**
+     * Subscribe to agent session events for UI updates.
+     *
+     * PURPOSE:
+     * Sets up the event subscription to agent session. All agent activity (messages,
+     * tool execution, compaction, retry, etc.) flows through here to update the display.
+     * This is the bridge between the agent execution layer and the TUI rendering layer.
+     *
+     * PROCESS:
+     * 1. Call session.subscribe() with an async event handler
+     * 2. Save unsubscribe function for cleanup on shutdown
+     * 3. Handler receives AgentSessionEvent objects and calls handleEvent()
+     * 4. handleEvent() dispatches based on event type to update UI components
+     *
+     * EVENT TYPES HANDLED:
+     * - `agent_start`: Show loading animation with working message
+     * - `message_start`: Create new message component (user/assistant/custom)
+     * - `message_update`: Stream content to message component, add tool calls
+     * - `message_end`: Mark message complete, update tool results
+     * - `tool_execution_start`: Create tool execution component in chat
+     * - `tool_execution_update`: Stream partial tool results
+     * - `tool_execution_end`: Mark tool complete with final result
+     * - `agent_end`: Hide loading animation, check for shutdown request
+     * - `auto_compaction_start`: Show compaction loader, allow escape to abort
+     * - `auto_compaction_end`: Hide loader, rebuild chat, flush queued messages
+     * - `auto_retry_start`: Show retry countdown loader
+     * - `auto_retry_end`: Hide loader, show error only on failure
+     *
+     * PARAMETERS:
+     * None - subscribes to this.session
+     *
+     * RETURNS:
+     * void - side effects only (sets this.unsubscribe)
+     *
+     * NOTES:
+     * - Called from init() after TUI is started
+     * - Handles streaming content incrementally
+     * - Must save unsubscribe function for cleanup in stop()
+     * - Events are processed sequentially (not concurrent)
+     */
     subscribeToAgent() {
         this.unsubscribe = this.session.subscribe(async (event) => {
             await this.handleEvent(event);
         });
     }
+    /**
+     * Handle a single agent session event and update the UI.
+     *
+     * PURPOSE:
+     * Processes agent events and translates them into UI updates. This is the main
+     * event dispatcher that receives all agent activity and renders it to the terminal.
+     *
+     * PROCESS FOR EACH EVENT TYPE:
+     *
+     * **agent_start**:
+     * - Stop any existing loading animation
+     * - Create new Loader component in statusContainer
+     * - Apply pending working message if queued
+     * - Request render
+     *
+     * **message_start**:
+     * - User messages: render to chat immediately
+     * - Assistant messages: create streaming component, add to chat
+     * - Custom messages: render with extension renderer
+     *
+     * **message_update**:
+     * - Stream new content to streamingComponent
+     * - For each tool call: create or update ToolExecutionComponent
+     * - Track tool components by ID for later result updates
+     *
+     * **message_end**:
+     * - Mark streaming complete
+     * - If aborted/error: set error message, mark all pending tools as error
+     * - Otherwise: trigger diff computation for edit tools
+     * - Clear streaming component reference
+     *
+     * **tool_execution_start/update/end**:
+     * - Create or update ToolExecutionComponent in chat
+     * - Stream partial results incrementally
+     * - On completion: mark expanded state and remove from pending
+     *
+     * **agent_end**:
+     * - Stop loading animation
+     * - Clear streaming component from chat
+     * - Clear pending tools
+     * - Check for shutdown request (if extension called shutdown())
+     *
+     * **auto_compaction_start**:
+     * - Show compaction loader with reason (overflow, etc.)
+     * - Replace main escape handler to allow abort
+     * - Editor stays active for queueing messages
+     *
+     * **auto_compaction_end**:
+     * - Hide loader
+     * - Rebuild chat to show compacted state
+     * - Add compaction summary component
+     * - Flush queued messages
+     * - Handle completion, cancellation, or errors
+     *
+     * **auto_retry_start**:
+     * - Show retry countdown (attempt N/M in delay seconds)
+     * - Replace main escape handler to allow abort
+     *
+     * **auto_retry_end**:
+     * - Hide loader
+     * - Show error only on final failure (success shows normal response)
+     *
+     * PARAMETERS:
+     * @param event - AgentSessionEvent (message, tool, compaction, retry, etc.)
+     *
+     * RETURNS:
+     * Promise<void> - completes when UI update is done
+     *
+     * STATE CHANGES:
+     * - Updates streamingComponent and streamingMessage
+     * - Updates pendingTools map
+     * - Updates loading animations (loadingAnimation, autoCompactionLoader, retryLoader)
+     * - Updates UI via this.ui.requestRender()
+     * - May call checkShutdownRequested() on agent_end
+     *
+     * NOTES:
+     * - Initializes if not yet initialized (lazy init)
+     * - Handles streaming content incremental rendering
+     * - Events are sequential, not concurrent
+     * - Tool components maintain expanded state across events
+     */
     async handleEvent(event) {
         if (!this.isInitialized) {
             await this.init();
@@ -1956,6 +2941,77 @@ export class InteractiveMode {
         this.lastStatusText = text;
         this.ui.requestRender();
     }
+    /**
+     * Render a single message to the chat display.
+     *
+     * PURPOSE:
+     * Converts an AgentMessage into one or more UI components and adds to chatContainer.
+     * Handles all message types with appropriate rendering, tool display, and formatting.
+     *
+     * MESSAGE TYPES HANDLED:
+     *
+     * **user**:
+     * - Extract text content (ignore images/other content)
+     * - Check for skill blocks (```skill block with instructions)
+     * - If skill block found:
+     *   a. Render SkillInvocationMessageComponent (collapsible)
+     *   b. Render user message separately if non-skill text exists
+     * - Otherwise render UserMessageComponent with full text
+     * - Optionally add to editor history for Up arrow recall
+     *
+     * **assistant**:
+     * - Create AssistantMessageComponent with streaming content
+     * - Respect hideThinkingBlock setting for visibility
+     * - Tool calls are handled separately in message_update event
+     *
+     * **custom**:
+     * - Check message.display flag (if false, skip rendering)
+     * - Use extension message renderer if available
+     * - Render as CustomMessageComponent with markdown theme
+     *
+     * **toolResult**:
+     * - Rendered inline with tool calls (not standalone)
+     * - Handled during renderSessionContext() matching with tool calls
+     *
+     * **bashExecution**:
+     * - Create BashExecutionComponent
+     * - Show command and real-time output
+     * - Mark complete with exit code and optional truncation info
+     *
+     * **compactionSummary**:
+     * - Show how many tokens were saved during compaction
+     * - Display summary of what was compacted
+     * - Component respects toolOutputExpanded setting
+     *
+     * **branchSummary**:
+     * - Show branch point with label
+     * - Display custom instructions for navigation
+     * - Component respects toolOutputExpanded setting
+     *
+     * PARAMETERS:
+     * @param message - AgentMessage to render (any role type)
+     * @param options.populateHistory - Add user text to editor history (default: false)
+     *
+     * RETURNS:
+     * void - side effects only (adds components to chatContainer)
+     *
+     * STATE CHANGES:
+     * - Adds components to chatContainer
+     * - May update editor history
+     * - Updates pendingTools map (indirectly in renderSessionContext)
+     *
+     * NOTES:
+     * - Uses getMarkdownThemeWithSettings() for consistent rendering
+     * - Respects current display settings (hideThinkingBlock, showImages, etc.)
+     * - Tool calls are created separately during message_update event
+     * - Skill blocks use parseSkillBlock() to extract instructions
+     * - Images in messages are handled by markdown renderer
+     * - Does NOT call ui.requestRender() (caller does)
+     *
+     * SEE ALSO:
+     * - renderSessionContext() which calls this for all messages
+     * - handleEvent() which creates components during streaming
+     */
     addMessageToChat(message, options) {
         switch (message.role) {
             case "bashExecution": {
@@ -2029,10 +3085,53 @@ export class InteractiveMode {
         }
     }
     /**
-     * Render session context to chat. Used for initial load and rebuild after compaction.
-     * @param sessionContext Session context to render
-     * @param options.updateFooter Update footer state
-     * @param options.populateHistory Add user messages to editor history
+     * Render a complete session context (all messages) to the chat display.
+     *
+     * PURPOSE:
+     * Renders all aligned messages from a SessionContext to the chat display.
+     * Handles message-to-tool-result matching and streaming state management.
+     * Used during initial load, after compaction, and during rebuilds.
+     *
+     * PROCESS:
+     * 1. Clear pendingTools map (reset tracking)
+     * 2. Iterate through all messages in context:
+     *    - Assistant messages: render message + create tool components for each tool call
+     *    - Tool result messages: match to tool component, update result, remove from pending
+     *    - Other messages: render via addMessageToChat()
+     * 3. Final clear of pendingTools (shouldn't have any left)
+     * 4. Call ui.requestRender() to display changes
+     *
+     * TOOL CALL/RESULT MATCHING:
+     * Tool calls and results are matched by ID:
+     * 1. When rendering assistant message, create ToolExecutionComponent for each tool call
+     * 2. Store component in pendingTools[toolCallId]
+     * 3. When rendering tool result: look up component, update it, remove from pending
+     * 4. If tool errored/aborted: mark component as error, don't add to pending
+     *
+     * PARAMETERS:
+     * @param sessionContext - SessionContext from sessionManager.buildSessionContext()
+     * @param options.updateFooter - Call footer.invalidate() and updateEditorBorderColor() (default: false)
+     * @param options.populateHistory - Add user message text to editor history (default: false)
+     *
+     * RETURNS:
+     * void - side effects only
+     *
+     * STATE CHANGES:
+     * - Clears and repopulates chatContainer
+     * - Updates pendingTools map (should be empty after completion)
+     * - May call footer.invalidate() if updateFooter is true
+     * - Calls ui.requestRender()
+     *
+     * NOTES:
+     * - Used internally by renderInitialMessages() and rebuildChatFromMessages()
+     * - All messages must be aligned (via sessionManager.buildSessionContext())
+     * - Tool calls/results must already be matched and in correct order
+     * - Error state is preserved from messages (stopReason, errorMessage)
+     * - Tool components track expanded state (respects this.toolOutputExpanded)
+     *
+     * SEE ALSO:
+     * - addMessageToChat() for individual message rendering
+     * - handleEvent() for streaming message handling
      */
     renderSessionContext(sessionContext, options = {}) {
         this.pendingTools.clear();
@@ -2086,6 +3185,56 @@ export class InteractiveMode {
         this.pendingTools.clear();
         this.ui.requestRender();
     }
+    /**
+     * Render all session messages to the chat display.
+     *
+     * PURPOSE:
+     * Displays all messages from the current session context in the chat area.
+     * Used when initializing the UI, resuming a session, or after compaction.
+     * Handles special message types: assistant, user, tool calls/results, compaction, branches.
+     *
+     * PROCESS:
+     * 1. Get aligned session messages from sessionManager.buildSessionContext()
+     * 2. Call renderSessionContext() to render all messages
+     * 3. Show compaction count if session was compacted (0+ times)
+     * 4. Update footer state (model, tokens, etc.)
+     * 5. Populate editor history with user messages for Up arrow
+     *
+     * MESSAGE TYPES RENDERED:
+     * - User messages: with text content and optional skill blocks
+     * - Assistant messages: with streaming content, thinking blocks, tool calls
+     * - Tool calls: inline with ToolExecutionComponent showing args and results
+     * - Tool results: rendered within tool components (not standalone)
+     * - Bash execution: with command and output
+     * - Compaction summary: shows how many tokens were saved
+     * - Branch summary: shows custom branch label/instructions
+     * - Custom messages: rendered via extension message renderer
+     *
+     * PARAMETERS:
+     * None - uses this.session and this.sessionManager
+     *
+     * RETURNS:
+     * void - side effects only (adds components to chatContainer)
+     *
+     * STATE CHANGES:
+     * - Populates chatContainer with all message components
+     * - Populates editor history
+     * - Updates footer.invalidate()
+     * - Updates pendingTools map for tracking tool components
+     * - Clears previous chat display
+     *
+     * NOTES:
+     * - Called from init() after UI setup
+     * - Called from run() before entering interactive loop
+     * - Called from resume/fork/tree navigation
+     * - Rebuilds entire chat, clearing previous messages
+     * - Compaction entries show as status messages
+     * - Only shows compaction info if compaction was performed
+     *
+     * SEE ALSO:
+     * - renderSessionContext() for detailed rendering logic
+     * - addMessageToChat() for rendering individual messages
+     */
     renderInitialMessages() {
         // Get aligned messages and entries from session context
         const context = this.sessionManager.buildSessionContext();
@@ -2109,6 +3258,43 @@ export class InteractiveMode {
             };
         });
     }
+    /**
+     * Rebuild chat display from scratch, clearing and re-rendering all messages.
+     *
+     * PURPOSE:
+     * Clears the entire chat display and re-renders all messages from session context.
+     * Used after toggling thinking block visibility, compaction completion, or theme changes.
+     * Ensures the display matches the current session state and settings.
+     *
+     * PROCESS:
+     * 1. Clear chatContainer (remove all rendered components)
+     * 2. Get fresh session context from sessionManager
+     * 3. Call renderSessionContext() to re-render all messages
+     * 4. All messages respect current settings (hideThinkingBlock, showImages, etc.)
+     *
+     * PARAMETERS:
+     * None - uses this.session and this.settingsManager
+     *
+     * RETURNS:
+     * void - side effects only
+     *
+     * STATE CHANGES:
+     * - Clears and repopulates chatContainer
+     * - Resets pendingTools map
+     * - Updates streaming/non-streaming component visibility
+     * - Respects current display settings
+     *
+     * NOTES:
+     * - Much faster than renderInitialMessages() (no footer update or history)
+     * - Used internally by toggleThinkingBlockVisibility()
+     * - Used after compaction to show new state
+     * - Does NOT scroll to top (chat scrolls naturally)
+     * - Triggers UI render request in renderSessionContext()
+     *
+     * SEE ALSO:
+     * - renderInitialMessages() for full initialization with footer/history
+     * - toggleThinkingBlockVisibility() which calls this
+     */
     rebuildChatFromMessages() {
         this.chatContainer.clear();
         const context = this.sessionManager.buildSessionContext();
@@ -2149,7 +3335,39 @@ export class InteractiveMode {
         process.exit(0);
     }
     /**
-     * Check if shutdown was requested and perform shutdown if so.
+     * Check if shutdown was requested and perform it if so.
+     *
+     * PURPOSE:
+     * Called after agent completes (agent_end event) to check if an extension
+     * has requested shutdown. Allows shutdown to be queued and executed cleanly
+     * after current operation completes.
+     *
+     * PROCESS:
+     * 1. Check this.shutdownRequested flag
+     * 2. If false: return (no shutdown requested)
+     * 3. If true: call shutdown()
+     *
+     * USAGE:
+     * - Extensions call context.shutdown() to request shutdown
+     * - Set this.shutdownRequested = true
+     * - After agent finishes, agent_end event triggers this check
+     * - Shutdown happens cleanly after current message completes
+     *
+     * PARAMETERS:
+     * None
+     *
+     * RETURNS:
+     * Promise<void> - never resolves (process.exit is called)
+     *
+     * NOTES:
+     * - Called from handleEvent() on agent_end
+     * - Defers shutdown until agent is idle
+     * - Allows current streaming/compaction to complete
+     * - Much cleaner than immediate exit
+     *
+     * SEE ALSO:
+     * - shutdown() which does the actual cleanup
+     * - handleEvent() which calls this on agent_end
      */
     async checkShutdownRequested() {
         if (!this.shutdownRequested)
@@ -2312,15 +3530,73 @@ export class InteractiveMode {
     // =========================================================================
     // UI helpers
     // =========================================================================
+    /**
+     * Clear the editor and request re-render.
+     *
+     * PURPOSE:
+     * Empties the editor text area. Used when user presses Escape with text.
+     */
     clearEditor() {
         this.editor.setText("");
         this.ui.requestRender();
     }
+    /**
+     * Show an error message in the chat.
+     *
+     * PURPOSE:
+     * Display an error message to the user. Used for command failures,
+     * parsing errors, and unexpected exceptions.
+     *
+     * PARAMETERS:
+     * @param errorMessage - The error message text (without "Error:" prefix)
+     *
+     * RETURNS:
+     * void - side effects only
+     *
+     * FORMATTING:
+     * - Adds 1-line spacer before message
+     * - Prefixes with "Error: "
+     * - Uses error color from theme
+     * - Adds to bottom of chat
+     *
+     * NOTES:
+     * - Auto-calls ui.requestRender()
+     * - Should be used for all errors displayed to user
+     * - Does not throw (safe to use in error handlers)
+     */
     showError(errorMessage) {
         this.chatContainer.addChild(new Spacer(1));
         this.chatContainer.addChild(new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0));
         this.ui.requestRender();
     }
+    /**
+     * Show a warning message in the chat.
+     *
+     * PURPOSE:
+     * Display a warning message to the user. Used for non-fatal issues,
+     * deprecated features, and important notifications.
+     *
+     * PARAMETERS:
+     * @param warningMessage - The warning message text (without "Warning:" prefix)
+     *
+     * RETURNS:
+     * void - side effects only
+     *
+     * FORMATTING:
+     * - Adds 1-line spacer before message
+     * - Prefixes with "Warning: "
+     * - Uses warning color from theme
+     * - Adds to bottom of chat
+     *
+     * NOTES:
+     * - Auto-calls ui.requestRender()
+     * - Similar to showError() but with different severity
+     * - Used for resource loading issues, model fallbacks, etc.
+     *
+     * SEE ALSO:
+     * - showError() for fatal errors
+     * - showStatus() for informational messages
+     */
     showWarning(warningMessage) {
         this.chatContainer.addChild(new Spacer(1));
         this.chatContainer.addChild(new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0));
@@ -2508,8 +3784,58 @@ export class InteractiveMode {
     // Selectors
     // =========================================================================
     /**
-     * Shows a selector component in place of the editor.
-     * @param create Factory that receives a `done` callback and returns the component and focus target
+     * Show a selector component, replacing the editor temporarily.
+     *
+     * PURPOSE:
+     * Generic helper to display selector dialogs (/settings, /model, /tree, etc.).
+     * Manages switching between the editor and selector, and restoring the editor.
+     *
+     * PROCESS:
+     * 1. Create done callback that:
+     *    a. Clears editorContainer
+     *    b. Restores this.editor as the focused component
+     *    c. Requests UI render
+     * 2. Call factory(done) to create the selector component
+     * 3. Factory returns { component, focus } where focus is initial focus target
+     * 4. Clear editorContainer and add selector component
+     * 5. Set focus to the focus component (usually the selector itself)
+     * 6. Request UI render
+     * 7. Selector calls done() when user makes selection or presses escape
+     *
+     * SELECTOR TYPES:
+     * - SettingsSelectorComponent: /settings - change settings
+     * - ModelSelectorComponent: /model - select a model
+     * - UserMessageSelectorComponent: /fork - pick message to branch from
+     * - TreeSelectorComponent: /tree - navigate session DAG
+     * - SessionSelectorComponent: /resume - switch to different session
+     * - OAuthSelectorComponent: /login or /logout - manage credentials
+     * - ExtensionSelectorComponent: custom dialogs from extensions
+     *
+     * PARAMETERS:
+     * @param create - Factory function that:
+     *   - Receives done() callback (selector calls when finished)
+     *   - Returns { component, focus } where component is the selector UI
+     *   - focus is the component to set focus to (keyboard input target)
+     *
+     * RETURNS:
+     * void - done callback handles restoration
+     *
+     * STATE CHANGES:
+     * - Temporarily replaces editor with selector in editorContainer
+     * - Sets keyboard focus to selector
+     * - On done: restores editor and focus
+     *
+     * NOTES:
+     * - Editor content is preserved (not cleared) during selector
+     * - Selector can be closed by pressing Escape
+     * - Factory receives done callback for flexible completion handling
+     * - Used by all major selectors (model, settings, fork, tree, etc.)
+     *
+     * SEE ALSO:
+     * - showModelSelector() for model selection
+     * - showSettingsSelector() for settings
+     * - showUserMessageSelector() for forking
+     * - showTreeSelector() for tree navigation
      */
     showSelector(create) {
         const done = () => {
@@ -2631,6 +3957,45 @@ export class InteractiveMode {
             return { component: selector, focus: selector.getSettingsList() };
         });
     }
+    /**
+     * Handle the /model command - select or switch models.
+     *
+     * PURPOSE:
+     * Process /model commands. If search term provided, find exact match.
+     * Otherwise show interactive selector. Supports both quick switch and browse.
+     *
+     * PROCESS:
+     * If searchTerm provided:
+     * 1. Call findExactModelMatch(searchTerm)
+     * 2. If found: switch to model, update footer/border, show status
+     * 3. If not found: show selector with search term as initial filter
+     *
+     * If no searchTerm:
+     * 1. Show model selector dialog
+     * 2. User picks a model
+     * 3. Model is switched
+     *
+     * SEARCH FORMAT:
+     * - "model-id": Match by model ID only
+     * - "provider/model-id": Match provider and model ID
+     * - Case-insensitive matching
+     *
+     * PARAMETERS:
+     * @param searchTerm - Optional model ID or "provider/model-id" to search for
+     *
+     * RETURNS:
+     * Promise<void> - completes when model is selected
+     *
+     * STATE CHANGES:
+     * - May call session.setModel() to switch
+     * - Updates footer.invalidate()
+     * - Updates editor border color (thinking level)
+     * - Shows status message
+     *
+     * SEE ALSO:
+     * - findExactModelMatch() for model lookup
+     * - showModelSelector() for interactive selection
+     */
     async handleModelCommand(searchTerm) {
         if (!searchTerm) {
             this.showModelSelector();
@@ -3805,6 +5170,46 @@ export class InteractiveMode {
         this.chatContainer.addChild(new Text(`${theme.fg("accent", "✓ New session started")}`, 1, 1));
         this.ui.requestRender();
     }
+    /**
+     * Handle the /debug command - write diagnostic information to file.
+     *
+     * PURPOSE:
+     * Generates a comprehensive debug log of the current terminal rendering state
+     * and agent message history. Used for troubleshooting rendering issues or
+     * unusual terminal behavior.
+     *
+     * PROCESS:
+     * 1. Get current terminal dimensions (columns x rows)
+     * 2. Call ui.render() to get all rendered lines at that width
+     * 3. Calculate visible width of each line (accounting for ANSI codes)
+     * 4. Collect all agent messages in JSONL format (one per line)
+     * 5. Write everything to debug log file (~/.indusagi/debug.log or similar)
+     * 6. Display success message with file path
+     *
+     * DEBUG LOG CONTENTS:
+     * - Timestamp of debug generation
+     * - Terminal dimensions (WxH)
+     * - Total rendered lines
+     * - All rendered lines with visible widths and ANSI-escaped content
+     * - All agent messages in JSONL format (one message object per line)
+     *
+     * PARAMETERS:
+     * None
+     *
+     * RETURNS:
+     * void - side effects only (writes file, shows status)
+     *
+     * STATE CHANGES:
+     * - Writes to disk (debug log file)
+     * - Adds status message to chat display
+     *
+     * NOTES:
+     * - File path: getDebugLogPath()
+     * - Creates parent directories if needed
+     * - Useful for reporting rendering bugs
+     * - Shows actual ANSI codes (escaped as JSON strings)
+     * - One message per line in JSONL section for easy parsing
+     */
     handleDebugCommand() {
         const width = this.ui.terminal.columns;
         const height = this.ui.terminal.rows;
@@ -3837,6 +5242,61 @@ export class InteractiveMode {
         this.chatContainer.addChild(new ArminComponent(this.ui));
         this.ui.requestRender();
     }
+    /**
+     * Handle bash command execution (! or !! prefix).
+     *
+     * PURPOSE:
+     * Executes a shell command and displays the output in a BashExecutionComponent.
+     * Supports including/excluding from context. Can be intercepted by extensions.
+     *
+     * PROCESS:
+     * 1. Emit user_bash event to extensions (if loaded)
+     * 2. If extension returns a result, use it (extension may intercept)
+     *    - Extensions can run custom operations or modify commands
+     * 3. Otherwise execute bash command normally:
+     *    a. Create BashExecutionComponent (shows command)
+     *    b. If streaming: add to pendingMessagesContainer, queue for chat
+     *    c. If idle: add directly to chatContainer
+     * 4. Stream output chunks to component in real-time
+     * 5. Mark complete with exit code and truncation status
+     * 6. Record result in session context
+     *
+     * CONTEXT HANDLING:
+     * - excludeFromContext=false (!): Output included in context for agent
+     * - excludeFromContext=true (!!): Output excluded from context
+     * - Extensions can define custom "operations" to transform output
+     *
+     * PARAMETERS:
+     * @param command - The bash command string (without ! or !! prefix)
+     * @param excludeFromContext - If true, mark output as excluded (!! prefix)
+     *
+     * RETURNS:
+     * Promise<void> - completes when command finishes
+     *
+     * STATE CHANGES:
+     * - Creates BashExecutionComponent
+     * - Adds to chatContainer or pendingMessagesContainer
+     * - Adds to pendingBashComponents if queued
+     * - Records bash result in session
+     * - Updates ui on each output chunk
+     *
+     * ERROR HANDLING:
+     * - Command failures caught and displayed as error message
+     * - Bash execution may be aborted by user (Esc)
+     * - Output may be truncated if too large
+     * - Truncation info shown with link to full output file
+     *
+     * NOTES:
+     * - User can check if bash is already running before executing
+     * - Extension can provide custom operations (e.g., parsing specific formats)
+     * - Output is streamed, so large outputs appear incrementally
+     * - Bash components moved from pending to chat on next regular message
+     * - Session.executeBash() handles actual execution and truncation
+     *
+     * SEE ALSO:
+     * - session.executeBash() for actual command execution
+     * - BashExecutionComponent for rendering
+     */
     async handleBashCommand(command, excludeFromContext = false) {
         const extensionRunner = this.session.extensionRunner;
         // Emit user_bash event to let extensions intercept
@@ -3904,6 +5364,33 @@ export class InteractiveMode {
         this.bashComponent = undefined;
         this.ui.requestRender();
     }
+    /**
+     * Handle the /compact command - manually trigger context compaction.
+     *
+     * PURPOSE:
+     * Allows user to manually compact the session context to reduce token usage.
+     * Can include custom instructions to guide the compaction process.
+     *
+     * PROCESS:
+     * 1. Count messages in session
+     * 2. If less than 2 messages: show warning and return (nothing to compact)
+     * 3. Otherwise call executeCompaction() with custom instructions
+     *
+     * PARAMETERS:
+     * @param customInstructions - Optional custom instructions for compaction process
+     *
+     * RETURNS:
+     * Promise<void> - completes when compaction is done
+     *
+     * NOTES:
+     * - User can press Esc during compaction to abort
+     * - Compaction may queue incoming messages
+     * - Custom instructions merged with default compaction prompt
+     *
+     * SEE ALSO:
+     * - executeCompaction() which does the actual work
+     * - auto-compaction (happens automatically based on context size)
+     */
     async handleCompactCommand(customInstructions) {
         const entries = this.sessionManager.getEntries();
         const messageCount = entries.filter((e) => e.type === "message").length;
@@ -3913,6 +5400,73 @@ export class InteractiveMode {
         }
         await this.executeCompaction(customInstructions, false);
     }
+    /**
+     * Execute context compaction (manual or automatic).
+     *
+     * PURPOSE:
+     * Compacts the session context to reduce token usage by summarizing old messages.
+     * Used both for manual /compact commands and automatic overflow-triggered compaction.
+     *
+     * PROCESS:
+     * 1. Stop and clear any existing loading animation
+     * 2. Replace escape handler to allow abort (Esc cancels compaction)
+     * 3. Show "Compacting context..." loader with estimated time
+     * 4. Call session.compact() with optional custom instructions
+     * 5. On success:
+     *    a. Rebuild chat to show compacted state
+     *    b. Add CompactionSummaryMessageComponent showing tokens saved
+     *    c. Invalidate footer (update token counts)
+     * 6. On abort/error:
+     *    a. Show error message
+     *    b. Chat state unchanged (compaction failed)
+     * 7. Flush queued messages that arrived during compaction
+     * 8. Restore original escape handler
+     * 9. Clear loader
+     *
+     * CUSTOM INSTRUCTIONS:
+     * - Optional guidance for compaction algorithm
+     * - Examples: "focus on recent messages", "preserve code context", etc.
+     * - Merged with default compaction system prompt
+     *
+     * AUTO vs MANUAL:
+     * - isAuto=false (/compact command): shows "Compacting context..." label
+     * - isAuto=true (automatic): shows "Auto-compacting..." label
+     * - auto-compaction triggered by context overflow (token limit)
+     *
+     * QUEUED MESSAGES:
+     * - Messages sent during compaction are queued in compactionQueuedMessages
+     * - After compaction completes, queued messages are flushed
+     * - First message becomes next prompt, rest queued as steer/followUp
+     *
+     * PARAMETERS:
+     * @param customInstructions - Optional custom instructions for compaction
+     * @param isAuto - If true, shows "Auto-compacting..." (default: false)
+     *
+     * RETURNS:
+     * Promise<CompactionResult | undefined> - returns result or undefined on error/abort
+     *
+     * STATE CHANGES:
+     * - Rebuilds chatContainer
+     * - Updates footer
+     * - Clears status container
+     * - Restores escape handler
+     * - Flushes compaction queue
+     *
+     * ERROR HANDLING:
+     * - Compaction cancelled: shows "Compaction cancelled" error
+     * - Compaction failed: shows detailed error message
+     * - Messages queued during compaction are preserved and flushed
+     *
+     * NOTES:
+     * - User can press Esc to abort
+     * - Loader shows "Ctrl+C to cancel" hint
+     * - Compaction happens asynchronously, UI stays responsive
+     * - Very large contexts may take several seconds
+     *
+     * SEE ALSO:
+     * - handleCompactCommand() for /compact processing
+     * - auto-compaction in handleEvent() for automatic triggering
+     */
     async executeCompaction(customInstructions, isAuto = false) {
         // Stop loading animation
         if (this.loadingAnimation) {