Files
hermes-agent/tests/cli/test_cli_shift_enter_newline.py

89 lines
2.9 KiB
Python
Raw Normal View History

feat(cli): recognise Shift+Enter as a newline key Closes #5346. Most terminals send the same byte sequence for `Enter` and `Shift+Enter` by default, so the application can't tell them apart — this is a terminal protocol limitation, not something Hermes can paper over. But terminals that implement the Kitty keyboard protocol (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal / Warp once the protocol is enabled) DO emit a distinct sequence for `Shift+Enter`: - `\x1b[13;2u` — Kitty / CSI-u, modifier=2 - `\x1b[27;2;13~` — xterm modifyOtherKeys=2 Stock prompt_toolkit doesn't have the CSI-u sequence in its `ANSI_SEQUENCES` table at all, and it maps the modifyOtherKeys variant to plain `Keys.ControlM` (Enter) — i.e. it strips the Shift modifier, which is the bug users actually hit on iTerm2 and friends. This PR adds `hermes_cli/pt_input_extras.install_shift_enter_alias()`, called once at CLI startup from `cli.py`, which inserts/overwrites those sequences in `ANSI_SEQUENCES` so they decode to `(Keys.Escape, Keys.ControlM)` — the same key tuple `Alt+Enter` produces. The existing Alt+Enter newline handler (`@kb.add('escape', 'enter')` in `cli.py`) then fires unchanged, so there is no new keybinding to register and no behavioral change for terminals that don't emit the distinct sequences. Files ===== * `hermes_cli/pt_input_extras.py` — new module hosting the helper. Lives outside `cli.py` so it's importable in tests without dragging in the full CLI runtime (which depends on `fire`, `rich`, etc.). * `cli.py` — calls `install_shift_enter_alias()` once at module import. Wrapped in try/except so prompt_toolkit version drift can't break CLI startup. * `tests/cli/test_cli_shift_enter_newline.py` — 6 tests: - registration of all three byte sequences - overwrite of stock prompt_toolkit's broken modifyOtherKeys mapping - idempotency - parser equivalence: CSI-u Shift+Enter == Alt+Enter - parser equivalence: modifyOtherKeys Shift+Enter == Alt+Enter - plain Enter remains a single key (submit), distinct from the two-key Alt+Enter / Shift+Enter tuple * `website/docs/user-guide/cli.md` — keybinding table updated; new "Shift+Enter compatibility" subsection with a per-terminal status table noting macOS Terminal / stock Windows Terminal cannot distinguish the keystroke at the protocol level. * `website/docs/getting-started/quickstart.md`, `website/docs/guides/tips.md` — short mention pointing readers at the full compatibility note in `cli.md`. Tested ====== pytest tests/cli/test_cli_shift_enter_newline.py # 6 passed Live-tested by triggering `\x1b[13;2u` against the running Vt100Parser (see test). Not exercised in a real terminal end-to-end because that requires a Kitty-protocol-capable host; the test exercises the parser path that drives the live terminal too.
2026-05-08 04:03:45 +05:30
"""Verify Shift+Enter byte sequences parse to the same key tuple Alt+Enter
produces, so the existing Alt+Enter newline handler in `cli.py` fires for
terminals that emit a distinct Shift+Enter under the Kitty keyboard protocol
or xterm modifyOtherKeys mode.
"""
from __future__ import annotations
import pytest
from prompt_toolkit.input.ansi_escape_sequences import ANSI_SEQUENCES
from prompt_toolkit.input.vt100_parser import Vt100Parser
from prompt_toolkit.keys import Keys
from hermes_cli.pt_input_extras import install_shift_enter_alias
SHIFT_ENTER_SEQUENCES = (
"\x1b[13;2u", # Kitty / CSI-u, modifier=2 (Shift)
"\x1b[27;2;13~", # xterm modifyOtherKeys=2
"\x1b[27;2;13u",
)
@pytest.fixture(autouse=True)
def _ensure_alias_installed():
"""Make every test idempotent — install the alias once per test run."""
install_shift_enter_alias()
def _parse(byte_seq: str):
out = []
parser = Vt100Parser(out.append)
for ch in byte_seq:
parser.feed(ch)
parser.flush()
return [kp.key for kp in out]
def test_install_registers_all_three_sequences():
for seq in SHIFT_ENTER_SEQUENCES:
assert seq in ANSI_SEQUENCES, f"missing mapping for {seq!r}"
assert ANSI_SEQUENCES[seq] == (Keys.Escape, Keys.ControlM)
def test_install_overwrites_stock_modifyotherkeys_shift_enter():
"""Stock prompt_toolkit maps `\\x1b[27;2;13~` to plain Keys.ControlM —
i.e. it drops the Shift modifier and treats Shift+Enter like Enter,
which is the bug this helper exists to fix. The install must overwrite
that entry."""
seq = "\x1b[27;2;13~"
ANSI_SEQUENCES[seq] = Keys.ControlM
install_shift_enter_alias()
assert ANSI_SEQUENCES[seq] == (Keys.Escape, Keys.ControlM)
def test_install_returns_zero_when_already_correct():
"""Idempotency — running install twice should not report a second change."""
install_shift_enter_alias()
assert install_shift_enter_alias() == 0
def test_csi_u_shift_enter_parses_as_alt_enter():
"""Kitty keyboard protocol Shift+Enter must parse to the same key tuple
Alt+Enter produces, so the existing handler is reused."""
alt_enter = _parse("\x1b\r")
shift_enter = _parse("\x1b[13;2u")
assert shift_enter == alt_enter, (
f"Shift+Enter via CSI-u should parse identically to Alt+Enter; "
f"got {shift_enter!r} vs {alt_enter!r}"
)
def test_modify_other_keys_shift_enter_parses_as_alt_enter():
"""xterm modifyOtherKeys=2 Shift+Enter must parse identically to Alt+Enter."""
alt_enter = _parse("\x1b\r")
shift_enter = _parse("\x1b[27;2;13~")
assert shift_enter == alt_enter
def test_plain_enter_remains_distinct_from_alt_enter():
"""Plain Enter must keep emitting a single key (submit), not a two-key
Alt+Enter tuple otherwise we would have broken submit."""
enter = _parse("\r")
alt_enter = _parse("\x1b\r")
assert enter != alt_enter
assert len(enter) == 1
assert len(alt_enter) == 2