mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-28 06:51:16 +08:00
a562420383
Problem: Ctrl+C in Hermes TUI shows 'copied' but clipboard often empty.
Root causes:
- Native Linux tools (xclip, wl-copy) require DISPLAY/WAYLAND_DISPLAY; in
headless Docker/SSH they fail or hang.
- OSC 52 fallback requires terminal emulator support; when absent, sequence
is dropped silently.
- Dashboard OSC 52 → Clipboard API path fails due to missing user gesture;
errors were silently caught.
- User feedback 'copied selection' was shown unconditionally, regardless of
success.
Solution implemented:
- Short-circuit Linux native clipboard probing when no display server is
present (no DISPLAY and no WAYLAND_DISPLAY). Avoids futile attempts and
timeouts.
- Add HERMES_TUI_DEBUG_CLIPBOARD env var (1/true). When set, TUI logs to
stderr which clipboard path is used, probe results on Linux, and whether
OSC 52 was emitted. Greatly improves diagnosability.
- Improve dashboard clipboard error handling: replace empty catch blocks
with console.warn messages for OSC 52 decode/Write failures and direct
copy/paste errors. Makes browser permission/user-gesture failures visible
in DevTools.
- Add comprehensive clipboard troubleshooting documentation to README and
AGENTS, covering OSC 52 verification, tmux config, Docker/headless
constraints, env vars, dashboard caveats, and fallback strategies.
Technical details:
- in ui-tui/packages/hermes-ink/src/ink/termio/osc.ts:
- Early return on Linux if both DISPLAY and WAYLAND_DISPLAY unset.
- Refactor probe sequence to async with 500ms timeout,
caching result; subsequent copies use cached tool immediately.
- Emit debug logs when HERMES_TUI_DEBUG_CLIPBOARD=1.
- in ink.tsx: log when OSC 52 not emitted (native
or tmux path in use) in debug mode.
- : OSC 52 handler and Ctrl+Shift+C handler now
log warnings to console on Clipboard API rejection with error message.
- Documentation: new 'Clipboard Troubleshooting' section in README; new
'Clipboard environment variables and pitfalls' subsection in AGENTS.md
(Known Pitfalls).
Tests: full ui-tui test suite (292 tests) passes; clipboard and OSC tests
unaffected. No breaking changes.
Files changed:
- ui-tui/packages/hermes-ink/src/ink/termio/osc.ts
- ui-tui/packages/hermes-ink/src/ink/ink.tsx
- web/src/pages/ChatPage.tsx
- README.md
- AGENTS.md
- CHANGELOG.md (new)
1.6 KiB
1.6 KiB
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Fixed
- TUI clipboard copy — Native tool probing on Linux now short-circuits immediately when
$DISPLAYand$WAYLAND_DISPLAYare both unset, avoiding wasted time and silent failures in headless environments (Docker, CI). (Hermes Ink / osc.ts) - TUI debug visibility — Added
HERMES_TUI_DEBUG_CLIPBOARDenvironment variable. When set, the TUI logs which clipboard mechanism is used, probe results, and why OSC 52 might be suppressed. Helps users and operators diagnose copy failures. - Dashboard clipboard logging — Silent failures in OSC 52 → Clipboard API bridge and direct
Ctrl+Shift+Ccopy are now logged to the browser console with explanatory warnings, replacing empty catch blocks. Makes clipboard permission issues and gesture-timeout failures visible during development. - Documentation — Added comprehensive "Clipboard Troubleshooting" section to README covering OSC 52 verification, tmux configuration, Docker/headless constraints, environment variables, and dashboard caveats. AGENTS.md now documents all clipboard-related environment variables and known failure modes.
Changed
- Desktop and dashboard clipboard error handling is now consistent: all Clipboard API rejections and native tool failures produce diagnostic logs rather than being swallowed.