fix(cli): decode raw arrow-key escape sequences in curses menus by kshitijk4poor · Pull Request #35776 · NousResearch/hermes-agent

kshitijk4poor · 2026-05-31T08:30:22Z

What

hermes setup (and any flow using the curses provider/model pickers) breaks the moment you press ↑ or ↓: navigation drops into the text Select [1-N] numbered fallback, and stray escape bytes leak into the next input().

Root cause

The curses menus in hermes_cli/curses_ui.py (curses_radiolist, curses_checklist, curses_single_select) decide what a key is from a single getch() value, matching only curses.KEY_UP / curses.KEY_DOWN.

Even with keypad(True) (which curses.wrapper sets), many terminals / terminfo entries deliver cursor keys as raw CSI/SS3 byte sequences. I reproduced this with a PTY harness: pressing arrow-down made getch() return 27, 91, 66 (ESC [ B) one byte at a time — not the translated curses.KEY_DOWN (258).

So the flow was:

↑/↓ → first byte 27 (ESC) arrives
27 matches the {27, ord("q")} cancel branch → menu returns its cancel sentinel
prompt_choice sees idx < 0 → falls through to the numbered Select [1-N] prompt
leftover bytes [B get consumed by the next input(), corrupting it

Fix

Add a shared read_menu_key() helper that decodes CSI/SS3 escape sequences into normalized NAV_* actions:

ESC [ A / ESC O A → up, ESC [ B / ESC O B → down
only a lone ESC (no continuation byte within a short timeout(60) window) still cancels — this also tolerates split sequences on slow SSH/tmux PTYs
any other escape sequence (Delete [3~, Home [H, End [F, …) is consumed up to its terminator and ignored, so its tail bytes can't leak into a later input()

All three curses menus route through the helper, so the translated KEY_* constants and vim j/k keep working too.

Validation

New tests/hermes_cli/test_curses_arrow_keys.py (11 tests): raw CSI/SS3 arrows decode to up/down, translated KEY_* still work, vim keys, lone-ESC cancels, q cancels, Enter variants select, and unhandled sequences (Delete/Home/End) are fully consumed without leaking trailing bytes.
pytest tests/hermes_cli/ -k 'curses or setup or menu or radio or checklist or select' → 224 passed, 0 regressions.

Note

This is the minimal root-cause fix. PR #8335 diagnosed the same issue but grew into a simple_term_menu→curses migration and was closed unmerged; this keeps the change scoped to escape-sequence decoding in the existing curses helpers.

The setup wizard's provider/model pickers (curses_radiolist via prompt_choice) bailed to the numbered "Select [1-N]" fallback the moment a user pressed up or down. Root cause: even with keypad(True) — which curses.wrapper sets — many terminals/terminfo entries deliver cursor keys to getch() as raw CSI/SS3 byte sequences (e.g. 27, 91, 66 for arrow-down) rather than the translated curses.KEY_DOWN. The menus matched only curses.KEY_UP/KEY_DOWN and treated the leading 27 (ESC) as cancel, so navigation dropped into the text fallback and the trailing bytes leaked into the next input(). Add a shared read_menu_key() helper that decodes CSI/SS3 escape sequences into normalized NAV_* actions (only a lone ESC, with no continuation byte within a short timeout, still cancels) and consumes the tail of unhandled sequences so stray bytes can't corrupt later input(). Route all three curses menus (checklist, radiolist, single_select) through it. Add regression tests covering raw CSI/SS3 arrows, translated KEY_* constants, vim keys, lone-ESC cancel, and full consumption of unhandled sequences (Delete/Home/End).

alt-glitch · 2026-05-31T08:34:35Z

Related: #8335 (closed, same bug class — curses arrow keys not decoded), #16370 (open, missing keypad(True) in session browser), #35126 (open, Kitty keyboard protocol variant), #7167 (merged, stdin flush after curses menus). This PR appears to be the most comprehensive fix with the read_menu_key() helper.

…o curses The setup provider->model sub-menu (and three sibling pickers) used simple_term_menu.TerminalMenu, whose ESC and arrow-key handling was unreliable across terminals — notably ESC failed to back out of the model selection list on terminals that emit raw escape sequences (e.g. Ghostty). The codebase already notes simple_term_menu 'conflicts with /dev/tty' and causes 'ghost-duplication rendering', and a prior attempt to migrate these (closed PR) confirmed the same root cause. Route all four single-select pickers through the shared, already-hardened curses_radiolist (which decodes raw CSI/SS3 escape sequences and handles ESC consistently, fixed in #35776): - auth.py _prompt_model_selection — model picker; the pricing column header and the unavailable-models block are passed as the radiolist description so they survive the curses screen clear. ESC now cancels. - main.py _prompt_reasoning_effort_selection — reasoning-effort picker. - main.py _model_flow_named_custom — named custom-provider model picker. - main.py _remove_custom_provider — provider-removal picker. simple_term_menu is no longer imported anywhere (only stale comments referenced it; one in setup.py is corrected). The numbered-input fallbacks are unchanged and still trigger on curses errors / non-TTY. Tests: updated test_terminal_menu_fallbacks / test_reasoning_effort_menu / test_custom_provider_model_switch / test_model_provider_persistence to drive the fallback via curses_radiolist errors instead of breaking simple_term_menu. New test_setup_menu_curses_migration.py asserts each picker routes through curses_radiolist, ESC cancels, and the pricing header is preserved. Net -147/+183 (mostly the new test file; production code shrinks by removing TerminalMenu boilerplate).

…o curses The setup provider->model sub-menu (and three sibling pickers) used simple_term_menu.TerminalMenu, whose ESC and arrow-key handling was unreliable across terminals — notably ESC failed to back out of the model selection list on terminals that emit raw escape sequences (e.g. Ghostty). The codebase already notes simple_term_menu 'conflicts with /dev/tty' and causes 'ghost-duplication rendering', and a prior attempt to migrate these (closed PR) confirmed the same root cause. Route all four single-select pickers through the shared, already-hardened curses_radiolist (which decodes raw CSI/SS3 escape sequences and handles ESC consistently, fixed in NousResearch#35776): - auth.py _prompt_model_selection — model picker; the pricing column header and the unavailable-models block are passed as the radiolist description so they survive the curses screen clear. ESC now cancels. - main.py _prompt_reasoning_effort_selection — reasoning-effort picker. - main.py _model_flow_named_custom — named custom-provider model picker. - main.py _remove_custom_provider — provider-removal picker. simple_term_menu is no longer imported anywhere (only stale comments referenced it; one in setup.py is corrected). The numbered-input fallbacks are unchanged and still trigger on curses errors / non-TTY. Tests: updated test_terminal_menu_fallbacks / test_reasoning_effort_menu / test_custom_provider_model_switch / test_model_provider_persistence to drive the fallback via curses_radiolist errors instead of breaking simple_term_menu. New test_setup_menu_curses_migration.py asserts each picker routes through curses_radiolist, ESC cancels, and the pricing header is preserved. Net -147/+183 (mostly the new test file; production code shrinks by removing TerminalMenu boilerplate).

fix(cli): decode raw arrow-key escape sequences in curses menus

…o curses The setup provider->model sub-menu (and three sibling pickers) used simple_term_menu.TerminalMenu, whose ESC and arrow-key handling was unreliable across terminals — notably ESC failed to back out of the model selection list on terminals that emit raw escape sequences (e.g. Ghostty). The codebase already notes simple_term_menu 'conflicts with /dev/tty' and causes 'ghost-duplication rendering', and a prior attempt to migrate these (closed PR) confirmed the same root cause. Route all four single-select pickers through the shared, already-hardened curses_radiolist (which decodes raw CSI/SS3 escape sequences and handles ESC consistently, fixed in #35776): - auth.py _prompt_model_selection — model picker; the pricing column header and the unavailable-models block are passed as the radiolist description so they survive the curses screen clear. ESC now cancels. - main.py _prompt_reasoning_effort_selection — reasoning-effort picker. - main.py _model_flow_named_custom — named custom-provider model picker. - main.py _remove_custom_provider — provider-removal picker. simple_term_menu is no longer imported anywhere (only stale comments referenced it; one in setup.py is corrected). The numbered-input fallbacks are unchanged and still trigger on curses errors / non-TTY. Tests: updated test_terminal_menu_fallbacks / test_reasoning_effort_menu / test_custom_provider_model_switch / test_model_provider_persistence to drive the fallback via curses_radiolist errors instead of breaking simple_term_menu. New test_setup_menu_curses_migration.py asserts each picker routes through curses_radiolist, ESC cancels, and the pricing header is preserved. Net -147/+183 (mostly the new test file; production code shrinks by removing TerminalMenu boilerplate).

…o curses The setup provider->model sub-menu (and three sibling pickers) used simple_term_menu.TerminalMenu, whose ESC and arrow-key handling was unreliable across terminals — notably ESC failed to back out of the model selection list on terminals that emit raw escape sequences (e.g. Ghostty). The codebase already notes simple_term_menu 'conflicts with /dev/tty' and causes 'ghost-duplication rendering', and a prior attempt to migrate these (closed PR) confirmed the same root cause. Route all four single-select pickers through the shared, already-hardened curses_radiolist (which decodes raw CSI/SS3 escape sequences and handles ESC consistently, fixed in NousResearch#35776): - auth.py _prompt_model_selection — model picker; the pricing column header and the unavailable-models block are passed as the radiolist description so they survive the curses screen clear. ESC now cancels. - main.py _prompt_reasoning_effort_selection — reasoning-effort picker. - main.py _model_flow_named_custom — named custom-provider model picker. - main.py _remove_custom_provider — provider-removal picker. simple_term_menu is no longer imported anywhere (only stale comments referenced it; one in setup.py is corrected). The numbered-input fallbacks are unchanged and still trigger on curses errors / non-TTY. Tests: updated test_terminal_menu_fallbacks / test_reasoning_effort_menu / test_custom_provider_model_switch / test_model_provider_persistence to drive the fallback via curses_radiolist errors instead of breaking simple_term_menu. New test_setup_menu_curses_migration.py asserts each picker routes through curses_radiolist, ESC cancels, and the pricing header is preserved. Net -147/+183 (mostly the new test file; production code shrinks by removing TerminalMenu boilerplate).

…rrow-key-decode fix(cli): decode raw arrow-key escape sequences in curses menus