Skip to content

Commit fa00356

Browse files
vinhnxvinhnx
committed
feat: restore Kitty keyboard protocol support and update session handling
1 parent 37a9694 commit fa00356

File tree

3 files changed

+205
-1
lines changed

3 files changed

+205
-1
lines changed

‎docs/KITTY_KEYBOARD_PROTOCOL_RESTORATION.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Kitty Keyboard Protocol Restoration
2+
3+
## Overview
4+
5+
This document describes the complete restoration of the Kitty keyboard protocol support in VT Code. The protocol allows modern terminals to send richer keyboard event information (press/release/repeat, alternate keys, etc.) to improve the user input experience.
6+
7+
Reference: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
8+
9+
## Architecture
10+
11+
The Kitty keyboard protocol is integrated at multiple layers of the TUI initialization pipeline:
12+
13+
```
14+
VTCodeConfig (vtcode.toml)
15+
↓
16+
KeyboardProtocolConfig (ui.keyboard_protocol)
17+
↓
18+
keyboard_protocol_to_flags() conversion
19+
↓
20+
TuiOptions / ModernTuiConfig
21+
↓
22+
Terminal mode setup (enable_terminal_modes / ModernTui.enter())
23+
↓
24+
PushKeyboardEnhancementFlags / PopKeyboardEnhancementFlags
25+
```
26+
27+
## Files Modified/Restored
28+
29+
### Core Configuration
30+
31+
#### vtcode-config/src/root.rs
32+
- **Status**: ✓ Already present
33+
- **Details**: Contains `KeyboardProtocolConfig` struct with fields:
34+
- `enabled`: Master toggle for keyboard protocol
35+
- `mode`: Preset modes ("default", "full", "minimal", "custom")
36+
- Individual flag controls for custom mode
37+
- **Defaults**: Enabled by default, using "default" mode
38+
- **Environment overrides**: `VTCODE_KEYBOARD_PROTOCOL_ENABLED`, `VTCODE_KEYBOARD_PROTOCOL_MODE`
39+
40+
#### vtcode-core/src/config/mod.rs
41+
- **Status**: ✓ Already present
42+
- **Details**:
43+
- Exports `KeyboardProtocolConfig`
44+
- Implements `keyboard_protocol_to_flags()` function that converts config to `KeyboardEnhancementFlags`
45+
- Includes comprehensive test suite for all modes
46+
47+
### TUI Layer - Modern Implementation
48+
49+
#### vtcode-core/src/ui/tui/modern_tui.rs
50+
- **Status**: ✓ Restored
51+
- **Changes**:
52+
- Added imports for keyboard protocol types
53+
- Added `keyboard_flags: KeyboardEnhancementFlags` field to `ModernTui` struct
54+
- Added `keyboard_flags()` builder method
55+
- Updated `enter()` to push keyboard flags if configured
56+
- Updated `exit()` to pop keyboard flags if configured
57+
- Updated `suspend()` to pop keyboard flags if configured
58+
59+
#### vtcode-core/src/ui/tui/modern_integration.rs
60+
- **Status**: ✓ Restored
61+
- **Changes**:
62+
- Added `keyboard_protocol: KeyboardProtocolConfig` field to `ModernTuiConfig`
63+
- Import `keyboard_protocol_to_flags` function
64+
- Convert config to flags before creating `ModernTui` instance
65+
- Pass flags through builder chain
66+
67+
### TUI Layer - Runner Implementation
68+
69+
#### vtcode-core/src/ui/tui/runner.rs
70+
- **Status**: ✓ Restored
71+
- **Changes**:
72+
- Added `keyboard_protocol: KeyboardProtocolConfig` field to `TuiOptions`
73+
- Extended `TerminalModeState` with `keyboard_enhancements_pushed` flag
74+
- Updated `enable_terminal_modes()` to:
75+
- Accept keyboard flags parameter
76+
- Push keyboard enhancement flags if enabled
77+
- Track state for cleanup
78+
- Updated `restore_terminal_modes()` to:
79+
- Pop keyboard enhancement flags if they were pushed
80+
- Execute in correct order (keyboard flags first)
81+
- Updated `run_tui()` to convert config and pass to mode setup
82+
83+
### Public API Layer
84+
85+
#### vtcode-core/src/ui/tui.rs
86+
- **Status**: ✓ Updated
87+
- **Changes**:
88+
- Added `keyboard_protocol: KeyboardProtocolConfig` parameter to `spawn_session_with_prompts()`
89+
- Updated `spawn_session()` to pass default config
90+
- Pass keyboard protocol through to `TuiOptions`
91+
92+
### Integration Point - Session Setup
93+
94+
#### src/agent/runloop/unified/session_setup.rs
95+
- **Status**: ✓ Updated
96+
- **Changes**:
97+
- Updated call to `spawn_session_with_prompts()` to pass actual keyboard protocol config
98+
- Extract from `vt_cfg.ui.keyboard_protocol` when available
99+
- Fall back to default when config not available
100+
101+
### Documentation & Comments
102+
103+
#### vtcode-core/src/ui/tui/alternate_screen.rs
104+
- **Status**: ✓ Comments already present
105+
- **Details**:
106+
- Documentation correctly mentions keyboard enhancement flags in lifecycle comments
107+
- Actual protocol implementation happens at higher TUI layer (modern_tui.rs, runner.rs)
108+
109+
#### vtcode-core/src/ui/tui/panic_hook.rs
110+
- **Status**: ✓ Already present
111+
- **Details**:
112+
- Properly imports and uses `PopKeyboardEnhancementFlags` in terminal restoration
113+
114+
## Configuration
115+
116+
### Default Behavior
117+
118+
By default, the keyboard protocol is:
119+
- **Enabled**: true
120+
- **Mode**: "default" (includes DISAMBIGUATE_ESCAPE_CODES, REPORT_EVENT_TYPES, REPORT_ALTERNATE_KEYS)
121+
122+
### Configuration Modes
123+
124+
```toml
125+
[ui.keyboard_protocol]
126+
enabled = true
127+
mode = "default" # Options: "default", "full", "minimal", "custom"
128+
```
129+
130+
#### Mode Details
131+
132+
- **default**:
133+
- DISAMBIGUATE_ESCAPE_CODES (resolve Esc key ambiguity)
134+
- REPORT_EVENT_TYPES (press/release/repeat events)
135+
- REPORT_ALTERNATE_KEYS (alternate key layouts)
136+
137+
- **full**:
138+
- All from "default" plus
139+
- REPORT_ALL_KEYS_AS_ESCAPE_CODES (modifier-only keys)
140+
141+
- **minimal**:
142+
- DISAMBIGUATE_ESCAPE_CODES only
143+
144+
- **custom**:
145+
- Individually controlled flags:
146+
- `disambiguate_escape_codes`
147+
- `report_event_types`
148+
- `report_alternate_keys`
149+
- `report_all_keys`
150+
151+
### Environment Variable Overrides
152+
153+
```bash
154+
export VTCODE_KEYBOARD_PROTOCOL_ENABLED=true
155+
export VTCODE_KEYBOARD_PROTOCOL_MODE=full
156+
```
157+
158+
## Data Flow
159+
160+
1. **Config Load**: `VTCodeConfig` loads from `vtcode.toml` and environment
161+
2. **Session Setup**: `session_setup.rs` reads `vt_cfg.ui.keyboard_protocol`
162+
3. **Session Spawn**: Passes config to `spawn_session_with_prompts()`
163+
4. **TUI Setup**: `run_tui()` or `run_modern_tui()` receives config
164+
5. **Flag Conversion**: `keyboard_protocol_to_flags()` converts to crossterm flags
165+
6. **Terminal Init**: `enable_terminal_modes()` pushes flags to terminal
166+
7. **Terminal Cleanup**: `restore_terminal_modes()` pops flags on exit
167+
168+
## Terminal Support
169+
170+
The Kitty keyboard protocol is supported by:
171+
- Kitty terminal emulator
172+
- WezTerm
173+
- Alacritty (with enabling)
174+
- iTerm2
175+
- Other modern terminals supporting CSI sequences
176+
177+
Terminals that don't support the protocol will safely ignore the ANSI escape sequences, so enabling is safe across environments.
178+
179+
## Testing
180+
181+
The restoration includes:
182+
- Unit tests in `vtcode-core/src/config/mod.rs` for `keyboard_protocol_to_flags()`
183+
- Tests for all mode conversions (default, full, minimal, custom)
184+
- Tests for disabled protocol
185+
- Tests for invalid mode handling
186+
187+
## Compilation Status
188+
189+
✓ Code compiles without errors
190+
✓ All dependencies resolve correctly
191+
✓ Backward compatible (defaults provided everywhere)
192+
193+
## Future Enhancements
194+
195+
Potential improvements:
196+
1. Runtime configuration changes (toggle keyboard protocol while running)
197+
2. Terminal detection (auto-enable for known-good terminals)
198+
3. Performance profiling with different keyboard protocol settings
199+
4. User documentation on keyboard protocol benefits

‎src/agent/runloop/unified/session_setup.rs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -726,6 +726,9 @@ pub(crate) async fn initialize_session_ui(
726726
Some(interrupt_callback),
727727
Some(session_state.custom_prompts.clone()),
728728
None,
729+
vt_cfg
730+
.map(|cfg| cfg.ui.keyboard_protocol.clone())
731+
.unwrap_or_default(),
729732
)
730733
.context("failed to launch inline session")?;
731734
let handle = session.clone_inline_handle();

‎vtcode-core/src/ui/tui.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ pub fn spawn_session(
4343
event_callback,
4444
None,
4545
active_pty_sessions,
46+
crate::config::KeyboardProtocolConfig::default(),
4647
)
4748
}
4849

@@ -56,6 +57,7 @@ pub fn spawn_session_with_prompts(
5657
event_callback: Option<InlineEventCallback>,
5758
custom_prompts: Option<crate::prompts::CustomPromptRegistry>,
5859
active_pty_sessions: Option<Arc<std::sync::atomic::AtomicUsize>>,
60+
keyboard_protocol: crate::config::KeyboardProtocolConfig,
5961
) -> Result<InlineSession> {
6062
use std::io::IsTerminal;
6163

@@ -83,7 +85,7 @@ pub fn spawn_session_with_prompts(
8385
event_callback,
8486
custom_prompts,
8587
active_pty_sessions,
86-
keyboard_protocol: crate::config::KeyboardProtocolConfig::default(),
88+
keyboard_protocol,
8789
},
8890
)
8991
.await

0 commit comments

Comments
 (0)