indusagi-coding-agent 0.1.29 → 0.1.30

package/docs/MODES-ARCHITECTURE.md

@@ -1,565 +0,0 @@
-# Modes Module - Complete Architecture Guide
-
-This document provides comprehensive documentation for the modes module, covering all three execution modes and their implementation details.
-
-## Table of Contents
-1. [Input System Documentation](#input-system-documentation)
-2. [Theme System Documentation](#theme-system-documentation)
-3. [Key Bindings Reference](#key-bindings-reference)
-4. [Print Mode Details](#print-mode-details)
-5. [RPC Mode Details](#rpc-mode-details)
-
----
-
-## Input System Documentation
-
-### Input States & State Machine
-
-The interactive mode uses a state machine to manage user input across different contexts:
-
-```
-States:
---------
-┌─────────────────────────────────────────────────┐
-│             Input State Machine                 │
-├─────────────────────────────────────────────────┤
-│                                                 │
-│  NORMAL                                         │
-│    ├── Regular typing → input buffer            │
-│    ├── Enter → submit prompt                    │
-│    ├── Tab → autocomplete                       │
-│    ├── Escape → clear                           │
-│    └── Ctrl+K → compaction mode                 │
-│                                                 │
-│  SELECTING (Model/Session/Config selector)     │
-│    ├── Up/Down → navigate options               │
-│    ├── Enter → select option                    │
-│    ├── Escape → cancel selection                │
-│    └── Type → filter options                    │
-│                                                 │
-│  EDITING (Multi-line editor)                   │
-│    ├── Alt+Enter → new line                     │
-│    ├── Ctrl+D → exit edit mode                  │
-│    ├── Up/Down → navigate history               │
-│    └── Ctrl+A/E → line start/end                │
-│                                                 │
-│  WAITING (Agent is processing)                 │
-│    ├── Ctrl+C → cancel request                 │
-│    ├── Display read-only output                │
-│    └── Prevent new input                        │
-│                                                 │
-└─────────────────────────────────────────────────┘
-```
-
-### Input Handling Pipeline
-
-```
-User Input
-    ↓
-InputHandler.parseInput()
-    ↓
-Check Extension Shortcuts (highest priority)
-    ↓
-Check App-level Keybindings (e.g., Ctrl+C)
-    ↓
-Check Slash Commands (/exit, /save, /branch, etc.)
-    ↓
-Validate Input
-    ↓
-Route to Handler
-    ├─ Agent prompt → submit to session
-    ├─ Command → execute command
-    └─ Extension action → pass to extension
-```
-
-### Key Binding System
-
-The CustomEditor component extends the base Editor with app-level keybindings management:
-
-**Key Binding Levels (priority order):**
-
-1. **Extension Shortcuts** (highest priority)
-   - Registered by extensions
-   - Custom keybindings for extension actions
-   - Example: Extension registers Ctrl+Shift+T for test runner
-
-2. **App-Level Actions** (medium priority)
-   - interrupt (Ctrl+C, Escape) - cancel operation
-   - pasteImage (Ctrl+Shift+V) - paste image from clipboard
-   - submitPrompt (Enter) - submit prompt
-   - compaction (Ctrl+K) - enter compaction mode
-   - Example: Ctrl+D to exit
-
-3. **Editor Keybindings** (lowest priority)
-   - Arrow keys, Ctrl+A/E, backspace, etc.
-   - Standard terminal editor shortcuts
-
-**Slash Commands** (text-based):
-
-Commands starting with "/" are parsed as slash commands:
-
-```
-/exit, /quit      - Exit interactive mode
-/save             - Save session to disk
-/branch [name]    - Create new session branch
-/switch [id]      - Switch to different session
-/compact          - Run compaction algorithm
-/clear            - Clear screen
-/help             - Show help
-/models           - List available models
-/settings         - Show settings dialog
-/theme [name]     - Change theme
-/sessions         - Browse session tree
-```
-
-### Autocomplete System
-
-Triggered with Ctrl+Space during text input:
-
-**Autocomplete Sources:**
-1. **Slash Commands** - `/exit`, `/save`, `/branch`, etc.
-2. **Bash Commands** - Common shell commands when prefixed with `$`
-3. **File Paths** - When typing file paths (starting with `.` or `/`)
-4. **Session IDs** - When switching sessions
-5. **Model Names** - When selecting models
-6. **Recent Inputs** - Previously typed prompts
-
-**Autocomplete Behavior:**
-- Filters suggestions based on typed text
-- Shows description for each suggestion
-- Press Up/Down to navigate suggestions
-- Press Enter to accept suggestion
-- Press Escape to dismiss autocomplete
-
-### Command History
-
-The editor maintains a command history for easy recall:
-
-- **Up Arrow** - Previous command
-- **Down Arrow** - Next command
-- **Ctrl+R** - Reverse search in history
-- **Ctrl+S** - Forward search in history
-
-History is persisted per session and includes:
-- User prompts sent to agent
-- Slash commands executed
-- Settings changes
-- Model/session selections
-
----
-
-## Theme System Documentation
-
-### Theme Structure
-
-Each theme is defined as a JSON file with the following structure:
-
-```json
-{
-  "name": "theme-name",
-  "extends": "default",
-  "colors": {
-    "agent": {
-      "fg": "blue",
-      "bg": null,
-      "bold": false,
-      "dim": false,
-      "italic": false
-    },
-    "user": {
-      "fg": "white",
-      "bold": true
-    },
-    "error": {
-      "fg": "red",
-      "bg": "black"
-    },
-    // ... more colors
-  },
-  "layout": {
-    "indent": 2,
-    "messageSpacing": 1,
-    "toolIndent": 4,
-    "maxWidth": 120
-  }
-}
-```
-
-### Available Colors
-
-**Message Colors:**
-- `agent` - AI assistant messages
-- `user` - User prompt messages
-- `assistant` - Assistant thinking/state
-- `error` - Error messages
-- `warning` - Warning messages
-- `info` - Information messages
-- `success` - Success messages
-
-**Component Colors:**
-- `tool` - Tool names and headers
-- `toolInput` - Tool input parameters
-- `toolOutput` - Tool output display
-- `code` - Code blocks and syntax
-- `codeKeyword` - Code keywords
-- `codeString` - Code string literals
-- `bash` - Bash command output
-- `bashError` - Bash error output
-
-**UI Colors:**
-- `selection` - Selected item in list
-- `border` - Box borders and dividers
-- `header` - Header text
-- `footer` - Footer text
-- `cursor` - Text cursor
-- `scrollbar` - Scrollbar indicator
-
-### Available Color Values
-
-Standard ANSI colors:
-- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
-- `brightBlack`, `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`
-
-Special values:
-- `null` - Inherit from terminal default
-- `#RRGGBB` - Hex colors (if terminal supports 24-bit colors)
-
-### Text Attributes
-
-Each color can have these attributes:
-- `bold: true|false` - Bold text
-- `dim: true|false` - Dimmed/faint text
-- `italic: true|false` - Italic text (if supported)
-- `underline: true|false` - Underlined text (if supported)
-- `inverse: true|false` - Inverted colors
-- `strikethrough: true|false` - Strikethrough text (if supported)
-
-### Creating a Custom Theme
-
-**Step 1: Create theme file**
-```
-mkdir -p ~/.indusagi/themes
-cat > ~/.indusagi/themes/mytheme.json << 'EOF'
-{
-  "name": "mytheme",
-  "extends": "dark",
-  "colors": {
-    "agent": {
-      "fg": "cyan"
-    },
-    "user": {
-      "fg": "brightGreen",
-      "bold": true
-    }
-  }
-}
-EOF
-```
-
-**Step 2: Use the theme**
-```bash
-indusagi --theme=mytheme
-```
-
-**Step 3: Set as default** (optional)
-```bash
-indusagi config set theme mytheme
-```
-
-### Theme Loading & Hot Reload
-
-**Loading Process:**
-1. Check user's `~/.indusagi/themes/` directory
-2. Check built-in themes in package
-3. Validate against JSON schema
-4. Merge with parent theme (if `extends` is set)
-5. Apply defaults for missing properties
-6. Load custom fonts (if specified)
-
-**Hot Reload:**
-The theme system watches for file changes in `~/.indusagi/themes/`:
-- If theme file is modified, changes apply immediately
-- No need to restart the application
-- Useful for iterating on custom themes
-
-### Theme Validation
-
-All themes are validated against `theme-schema.json` which enforces:
-- Required fields (name)
-- Valid color names
-- Valid attribute types
-- Proper nesting of properties
-- Type correctness
-
----
-
-## Key Bindings Reference
-
-### Default Interactive Mode Keybindings
-
-**Editor Navigation:**
-| Keybinding | Action |
-|------------|--------|
-| Ctrl+A | Move to start of line |
-| Ctrl+E | Move to end of line |
-| Ctrl+B | Move cursor back (left) |
-| Ctrl+F | Move cursor forward (right) |
-| Alt+B | Move word backward |
-| Alt+F | Move word forward |
-
-**Editing:**
-| Keybinding | Action |
-|------------|--------|
-| Backspace | Delete character before cursor |
-| Delete | Delete character at cursor |
-| Ctrl+D | Exit editor / delete char at cursor |
-| Ctrl+H | Backspace (alternative) |
-| Ctrl+K | Delete to end of line |
-| Ctrl+U | Delete to start of line |
-| Ctrl+W | Delete word before cursor |
-| Alt+D | Delete word after cursor |
-
-**Multi-line Editing:**
-| Keybinding | Action |
-|------------|--------|
-| Enter | Submit prompt (if not in edit mode) |
-| Alt+Enter | New line (while in edit mode) |
-| Ctrl+M | Alternative: new line |
-
-**History Navigation:**
-| Keybinding | Action |
-|------------|--------|
-| Up Arrow | Previous command in history |
-| Down Arrow | Next command in history |
-| Ctrl+R | Reverse search in history |
-| Ctrl+S | Forward search in history |
-| Ctrl+P | Previous (alternative to Up) |
-| Ctrl+N | Next (alternative to Down) |
-
-**Special Actions:**
-| Keybinding | Action |
-|------------|--------|
-| Ctrl+C | Cancel current operation / interrupt agent |
-| Escape | Exit autocomplete / dismiss dialog |
-| Ctrl+Space | Trigger autocomplete |
-| Ctrl+Shift+V | Paste image from clipboard |
-| Tab | Autocomplete (if showing suggestions) |
-
-**Session/Mode Commands (Slash Commands):**
-| Command | Action |
-|---------|--------|
-| /exit, /quit | Exit interactive mode |
-| /save | Save session to disk |
-| /branch [name] | Create new session branch |
-| /switch [id] | Switch to different session |
-| /compact | Run compaction on messages |
-| /clear | Clear screen |
-| /help | Show help |
-| /models | List available models |
-| /theme [name] | Change active theme |
-| /sessions | Browse session tree |
-
-### Customizing Keybindings
-
-Keybindings can be customized via configuration:
-
-```json
-{
-  "keybindings": {
-    "interrupt": ["ctrl+c", "ctrl+x"],
-    "submitPrompt": ["enter"],
-    "pasteImage": ["ctrl+shift+v"],
-    "customAction": ["ctrl+alt+s"]
-  }
-}
-```
-
----
-
-## Print Mode Details
-
-### Output Format Specifications
-
-**JSON Mode** - Machine-readable event stream:
-```json
-{"type": "message_start", "role": "user", "content": "Hello"}
-{"type": "agent_start", "model": "gpt-4"}
-{"type": "message_start", "role": "assistant", "content": "Hi there!"}
-{"type": "message_end"}
-```
-
-**TEXT Mode** - Human-readable output:
-```
-User: Hello
-Agent: Hi there!
-
-Session: abc123
-Model: gpt-4
-Tokens: 1,523 (est. ~1,142 words)
-```
-
-**COMPACT Mode** - Minimal output:
-```
-Hi there!
-```
-
-### Exit Codes
-
-| Code | Meaning | Use Case |
-|------|---------|----------|
-| 0 | Success | All operations completed successfully |
-| 1 | General Error | Unexpected error during execution |
-| 2 | Invalid Arguments | Invalid CLI arguments or options |
-| 3 | Session Not Found | Specified session doesn't exist |
-| 4 | Tool Execution Failed | Error executing a tool or bash command |
-| 5 | Model Error | Model unavailable, quota exceeded, etc. |
-| 6 | Timeout | Operation exceeded time limit |
-| 127 | Unknown Error | Unhandled exception or unknown error |
-
----
-
-## RPC Mode Details
-
-### RPC Protocol Basics
-
-JSON-RPC 2.0 over stdin/stdout or Unix socket:
-
-```json
-// Command with ID (expects response)
-{
-  "jsonrpc": "2.0",
-  "id": "req-1",
-  "method": "prompt",
-  "params": {
-    "message": "What does this code do?"
-  }
-}
-
-// Response
-{
-  "jsonrpc": "2.0",
-  "id": "req-1",
-  "result": {
-    "success": true,
-    "message": "This code..."
-  }
-}
-
-// Notification (no response expected)
-{
-  "jsonrpc": "2.0",
-  "method": "ping"
-}
-
-// Event (sent from server to client)
-{
-  "jsonrpc": "2.0",
-  "method": "event",
-  "params": {
-    "type": "agent_start",
-    "timestamp": 1677000000000
-  }
-}
-```
-
-### RPC Command Categories
-
-**Session Management:**
-- `session.create` - Create new session
-- `session.list` - List available sessions
-- `session.load` - Load session by ID
-- `session.save` - Save current session
-- `session.export` - Export session to HTML/JSON
-- `session.delete` - Delete session
-
-**Prompting:**
-- `prompt` - Send prompt to agent
-- `followUp` - Send follow-up without waiting
-- `steer` - Queue prompt during execution
-
-**Model Control:**
-- `setModel` - Change active model
-- `getModels` - List available models
-- `setThinking` - Set thinking level
-
-**State Management:**
-- `compact` - Run compaction
-- `branch` - Create session branch
-- `undo` - Undo last action
-- `getState` - Get session state
-
-**Bash Commands:**
-- `bash.execute` - Run bash command
-- `bash.kill` - Kill running bash process
-
-### RPC Error Codes
-
-| Code | Category | Meaning |
-|------|----------|---------|
-| -32700 | Parse Error | Invalid JSON received |
-| -32600 | Invalid Request | Malformed request object |
-| -32601 | Method Not Found | Unknown method called |
-| -32602 | Invalid Params | Invalid method parameters |
-| -32603 | Internal Error | Server error |
-| -32000 | Server Error: Session not found |
-| -32001 | Server Error: Invalid prompt |
-| -32002 | Server Error: Tool execution failed |
-| -32003 | Server Error: Model error |
-| -32004 | Server Error: Timeout |
-| -32005 | Server Error: Authentication required |
-
-### RPC Authentication & Security
-
-**Supported Methods:**
-1. **Token-based** - Pass token in header or params
-2. **File-based** - Read token from `~/.indusagi/rpc-token`
-3. **Environment** - `INDUSAGI_RPC_TOKEN` env var
-4. **No Auth** - For local/trusted connections only
-
-**Security Considerations:**
-- Always use HTTPS/Unix sockets for remote connections
-- Never expose RPC over public networks without auth
-- Token should have sufficient entropy (32+ bytes)
-- Rotate tokens regularly for long-lived connections
-- Log all RPC calls for audit trails
-
-### RPC Connection Management
-
-**Lifecycle:**
-
-```
-Client                    Server
-  │                         │
-  ├─ Connect ──────────────>│
-  │                         │
-  ├─ Subscribe events ──────>│
-  │                         │
-  ├─ Send commands ────────>│
-  │                    <──── Responses
-  │                    <──── Events
-  │                         │
-  ├─ Disconnect ──────────>│
-  │                         │
-```
-
-**Connection Options:**
-- `host` - Server hostname (default: localhost)
-- `port` - Server port (default: 3000)
-- `socket` - Unix socket path (prefer over TCP)
-- `timeout` - Request timeout in ms (default: 30000)
-- `retries` - Number of retries on failure (default: 3)
-
-**Reconnection Strategy:**
-- Exponential backoff: 100ms, 200ms, 400ms, 800ms...
-- Max delay: 30 seconds
-- Automatic reconnection on disconnect
-- Requeue pending requests after reconnect
-
----
-
-## Additional Resources
-
-- See `src/modes/shared.ts` for utility functions
-- See `src/modes/interactive-mode.ts` for event handling
-- See `src/modes/print-mode.ts` for output formatting
-- See `src/modes/rpc/` for RPC implementation