indusagi-coding-agent 0.1.46 → 0.1.48

package/dist/interfaces/terminal-ui/interactive-mode.d.ts

@@ -1,1941 +0,0 @@
-/**
- * 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 { type ImageContent } from "indusagi/ai";
-import { type AgentSession } from "../../runtime/agent-session.js";
-/**
- * Options for InteractiveMode initialization.
- */
-export interface InteractiveModeOptions {
-    /** Providers that were migrated to auth.json (shows warning) */
-    migratedProviders?: string[];
-    /** Warning message if session model couldn't be restored */
-    modelFallbackMessage?: string;
-    /** Initial message to send on startup (can include @file content) */
-    initialMessage?: string;
-    /** Images to attach to the initial message */
-    initialImages?: ImageContent[];
-    /** Additional messages to send after the initial message */
-    initialMessages?: string[];
-    /** Force verbose startup (overrides quietStartup setting) */
-    verbose?: boolean;
-}
-/**
- * ============================================================================
- * 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 declare class InteractiveMode {
-    private options;
-    private session;
-    private ui;
-    private chatContainer;
-    private pendingMessagesContainer;
-    private statusContainer;
-    private defaultEditor;
-    private editor;
-    private autocompleteProvider;
-    private fdPath;
-    private editorContainer;
-    private footer;
-    private footerDataProvider;
-    private keybindings;
-    private version;
-    private isInitialized;
-    private onInputCallback?;
-    private loadingAnimation;
-    private pendingWorkingMessage;
-    private readonly defaultWorkingMessage;
-    private lastSigintTime;
-    private lastEscapeTime;
-    private changelogMarkdown;
-    private lastStatusSpacer;
-    private lastStatusText;
-    private streamingComponent;
-    private streamingMessage;
-    private pendingTools;
-    private toolOutputExpanded;
-    private hideThinkingBlock;
-    private skillCommands;
-    private unsubscribe?;
-    private isBashMode;
-    private bashComponent;
-    private pendingBashComponents;
-    private autoCompactionLoader;
-    private autoCompactionEscapeHandler?;
-    private retryLoader;
-    private retryEscapeHandler?;
-    private compactionQueuedMessages;
-    private shutdownRequested;
-    private extensionSelector;
-    private extensionInput;
-    private extensionEditor;
-    private extensionWidgetsAbove;
-    private extensionWidgetsBelow;
-    private widgetContainerAbove;
-    private widgetContainerBelow;
-    private customFooter;
-    private builtInHeader;
-    private customHeader;
-    private get agent();
-    private get sessionManager();
-    private get settingsManager();
-    constructor(session: AgentSession, options?: InteractiveModeOptions);
-    private setupAutocomplete;
-    private rebuildAutocomplete;
-    private prepareStartupResources;
-    private buildStartupHeader;
-    private attachMainLayout;
-    private activateInteractiveRuntime;
-    private showStartupWarnings;
-    private processStartupMessages;
-    /**
-     * 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
-     */
-    init(): Promise<void>;
-    /**
-     * Update terminal title with session name and cwd.
-     */
-    private updateTerminalTitle;
-    /**
-     * 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
-     */
-    run(): Promise<void>;
-    /**
-     * Check npm registry for a newer version.
-     */
-    private checkForNewVersion;
-    /**
-     * Get changelog entries to display on startup.
-     * Only shows new entries since last seen version, skips for resumed sessions.
-     */
-    private getChangelogForDisplay;
-    private getStartupImageComponent;
-    private getMarkdownThemeWithSettings;
-    private formatDisplayPath;
-    /**
-     * Get a short path relative to the package root for display.
-     */
-    private getShortPath;
-    private getDisplaySourceInfo;
-    private getScopeGroup;
-    private isPackageSource;
-    private buildScopeGroups;
-    private formatScopeGroups;
-    /**
-     * Find metadata for a path, checking parent directories if exact match fails.
-     * Package manager stores metadata for directories, but we display file paths.
-     */
-    private findMetadata;
-    /**
-     * Format a path with its source/scope info from metadata.
-     */
-    private formatPathWithSource;
-    /**
-     * Format resource diagnostics with nice collision display using metadata.
-     */
-    private formatDiagnostics;
-    private showLoadedResources;
-    /**
-     * 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
-     */
-    private initExtensions;
-    /**
-     * Get a registered tool definition by name (for custom rendering).
-     */
-    private getRegisteredToolDefinition;
-    /**
-     * Set up keyboard shortcuts registered by extensions.
-     */
-    private setupExtensionShortcuts;
-    /**
-     * Set extension status text in the footer.
-     */
-    private setExtensionStatus;
-    /**
-     * Set an extension widget (string array or custom component).
-     */
-    private setExtensionWidget;
-    private clearExtensionWidgets;
-    private resetExtensionUI;
-    private static readonly MAX_WIDGET_LINES;
-    /**
-     * Render all extension widgets to the widget container.
-     */
-    private renderWidgets;
-    private renderWidgetContainer;
-    /**
-     * Set a custom footer component, or restore the built-in footer.
-     */
-    private setExtensionFooter;
-    /**
-     * Set a custom header component, or restore the built-in header.
-     */
-    private setExtensionHeader;
-    /**
-     * Create the ExtensionUIContext for extensions.
-     */
-    private createExtensionUIContext;
-    /**
-     * Show a selector for extensions.
-     */
-    private showExtensionSelector;
-    /**
-     * Hide the extension selector.
-     */
-    private hideExtensionSelector;
-    /**
-     * Show a confirmation dialog for extensions.
-     */
-    private showExtensionConfirm;
-    /**
-     * Show a text input for extensions.
-     */
-    private showExtensionInput;
-    /**
-     * Hide the extension input.
-     */
-    private hideExtensionInput;
-    /**
-     * Show a multi-line editor for extensions (with Ctrl+G support).
-     */
-    private showExtensionEditor;
-    /**
-     * Hide the extension editor.
-     */
-    private hideExtensionEditor;
-    /**
-     * Set a custom editor component from an extension.
-     * Pass undefined to restore the default editor.
-     */
-    private setCustomEditorComponent;
-    /**
-     * Show a notification for extensions.
-     */
-    private showExtensionNotify;
-    /** Show a custom component with keyboard focus. Overlay mode renders on top of existing content. */
-    private showExtensionCustom;
-    /**
-     * Show an extension error in the UI.
-     */
-    private showExtensionError;
-    /**
-     * Show a hook error in the UI.
-     */
-    private showHookError;
-    /**
-     * 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
-     */
-    private setupKeyHandlers;
-    private handleClipboardImagePaste;
-    /**
-     * 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
-     */
-    private setupEditorSubmitHandler;
-    /**
-     * 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)
-     */
-    private subscribeToAgent;
-    /**
-     * 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
-     */
-    private handleEvent;
-    /** Extract text content from a user message */
-    private getUserMessageText;
-    /**
-     * Show a status message in the chat.
-     *
-     * If multiple status messages are emitted back-to-back (without anything else being added to the chat),
-     * we update the previous status line instead of appending new ones to avoid log spam.
-     */
-    private showStatus;
-    /**
-     * 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
-     */
-    private addMessageToChat;
-    /**
-     * 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
-     */
-    private renderSessionContext;
-    /**
-     * 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(): void;
-    getUserInput(): Promise<string>;
-    /**
-     * 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
-     */
-    private rebuildChatFromMessages;
-    private handleCtrlC;
-    private handleCtrlD;
-    /**
-     * 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
-     */
-    private isShuttingDown;
-    private shutdown;
-    /**
-     * 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
-     */
-    private checkShutdownRequested;
-    private handleCtrlZ;
-    private handleFollowUp;
-    private handleDequeue;
-    private updateEditorBorderColor;
-    private cycleThinkingLevel;
-    private cycleModel;
-    private toggleToolOutputExpansion;
-    private toggleThinkingBlockVisibility;
-    private openExternalEditor;
-    /**
-     * Clear the editor and request re-render.
-     *
-     * PURPOSE:
-     * Empties the editor text area. Used when user presses Escape with text.
-     */
-    clearEditor(): void;
-    /**
-     * 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: string): void;
-    /**
-     * 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: string): void;
-    showNewVersionNotification(newVersion: string): void;
-    /**
-     * Get all queued messages (read-only).
-     * Combines session queue and compaction queue.
-     */
-    private getAllQueuedMessages;
-    /**
-     * Clear all queued messages and return their contents.
-     * Clears both session queue and compaction queue.
-     */
-    private clearAllQueues;
-    private updatePendingMessagesDisplay;
-    private restoreQueuedMessagesToEditor;
-    private queueCompactionMessage;
-    private isExtensionCommand;
-    private flushCompactionQueue;
-    /** Move pending bash components from pending area to chat */
-    private flushPendingBashComponents;
-    /**
-     * 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
-     */
-    private showSelector;
-    private showSettingsSelector;
-    /**
-     * 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
-     */
-    private handleModelCommand;
-    private findExactModelMatch;
-    private getModelCandidates;
-    /** Update the footer's available provider count from current model candidates */
-    private updateAvailableProviderCount;
-    private showModelSelector;
-    private showModelsSelector;
-    private showUserMessageSelector;
-    private showTreeSelector;
-    private showSessionSelector;
-    private handleResumeSession;
-    private showOAuthSelector;
-    /**
-     * Show account selector for providers with multiple accounts
-     */
-    private showAccountSelector;
-    /**
-     * Prompt for account name, then proceed with OAuth or API key login
-     */
-    private showNewAccountNameDialog;
-    /**
-     * OAuth login with a specific account name
-     */
-    private showLoginDialogWithAccountName;
-    /**
-     * API key input with a specific account name
-     */
-    private showApiKeyInputDialogWithName;
-    private showLoginDialog;
-    private showApiKeyDialog;
-    /**
-     * Show API key input dialog for adding a new account
-     */
-    private showApiKeyInputDialog;
-    private handleReloadCommand;
-    /**
-     * Handle MCP (Model Context Protocol) commands.
-     *
-     * Subcommands:
-     * - "" (empty): Show MCP status
-     * - "connect": Connect to MCP servers
-     * - "disconnect": Disconnect from MCP servers
-     * - "tools": List available MCP tools
-     */
-    private handleMCPCommand;
-    /**
-     * Handle /memory commands for memory system management.
-     * Sub-commands:
-     * - "" / "status": Show memory status
-     * - "on": Enable memory for current and future sessions
-     * - "off": Disable memory for current and future sessions
-     * - "setup <api-key>": Save OpenAI API key and enable memory
-     * - "clear": Clear memory for current thread
-     * - "working": Show working memory for current thread
-     * - "tools": List memory tools
-     */
-    private handleMemoryCommand;
-    /**
-     * Handle /composio commands for Composio runtime management.
-     * Sub-commands:
-     * - "" / "status": Show control-tool and hydrated-tool status
-     * - "enable <toolkit[,toolkit]>": Hydrate toolkit tools into the current session
-     * - "tools": List hydrated Composio toolkit tools
-     * - "accounts [toolkit[,toolkit]]": List connected accounts
-     * - "clear": Remove hydrated Composio toolkit tools from the current session
-     */
-    private handleComposioCommand;
-    private handleExportCommand;
-    private handleShareCommand;
-    private handleCopyCommand;
-    private handleNameCommand;
-    private handleSessionCommand;
-    private handleChangelogCommand;
-    /**
-     * Capitalize keybinding for display (e.g., "ctrl+c" -> "Ctrl+C").
-     */
-    private capitalizeKey;
-    /**
-     * Get capitalized display string for an app keybinding action.
-     */
-    private getAppKeyDisplay;
-    /**
-     * Get capitalized display string for an editor keybinding action.
-     */
-    private getEditorKeyDisplay;
-    private handleHotkeysCommand;
-    private handleClearCommand;
-    /**
-     * 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
-     */
-    private handleDebugCommand;
-    private handleArminSaysHi;
-    /**
-     * 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
-     */
-    private handleBashCommand;
-    /**
-     * 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)
-     */
-    private handleCompactCommand;
-    /**
-     * 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
-     */
-    private executeCompaction;
-    stop(): void;
-}
-//# sourceMappingURL=interactive-mode.d.ts.map