feat(gateway): configure Telegram command menu priority

[thestral123]

What does this PR do?

This PR makes the Telegram BotCommand menu priority and visible-menu cap configurable from the documented Telegram platform config path:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 30
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

Telegram command registration currently uses a safe 30-command cap to avoid Telegram's payload-size limits. That preserves reliability, but local/plugin/skill commands can be pushed out of the visible / picker by built-in defaults. This change keeps the existing default behavior while letting users explicitly prioritize the commands they need visible.

The approach is intentionally narrow:

• keeps the existing default cap of 30 commands
• clamps configured caps to Telegram's 1..100 BotCommand limit
• supports prepend, append, and replace priority modes
• uses only the documented platforms.telegram.extra.command_menu path
• does not change command dispatch: hidden commands remain invokable when typed manually, and /commands remains the full list

This overlaps with the user need in #33480 and is related to earlier proposals such as #31099, #34147, #33706, #33484, and #40325. The main difference is that this combines configurable priority and cap under the documented platform extra.command_menu config surface while preserving the safe default behavior.

Related Issue

Fixes #33480

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• hermes_cli/commands.py
  • adds Telegram command-menu config parsing from platforms.telegram.extra.command_menu
  • adds safe normalization for max_commands, priority_mode, and priority
  • applies configured priorities before Telegram menu truncation
• gateway/platforms/telegram.py
  • uses the configured cap when registering default and chat-scoped Telegram BotCommands
  • keeps the default cap at 30
• tests/hermes_cli/test_commands.py
  • covers configured plugin command priority
  • covers prepend, append, and replace behavior
  • covers max_commands defaults, clamping, invalid values, and ignoring undocumented paths
• cli-config.yaml.example
  • documents the new Telegram command-menu config block
• website/docs/user-guide/messaging/telegram.md
  • documents how Telegram menu priority/cap config works and clarifies that /commands remains the full list

How to Test

1. Configure a Telegram command-menu priority list in ~/.hermes/config.yaml:

   platforms:
     telegram:
       extra:
         command_menu:
           max_commands: 30
           priority_mode: prepend
           priority:
             - my_plugin_command

2. Restart the Telegram gateway so BotCommands are re-registered.

3. Open Telegram's / picker and verify the configured command appears before lower-priority defaults.

4. Run the automated checks:

   scripts/run_tests.sh tests/hermes_cli/test_commands.py
   python scripts/check-windows-footguns.py --diff upstream/main
   git diff --check upstream/main...HEAD

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu/Linux

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Verification performed

scripts/run_tests.sh tests/hermes_cli/test_commands.py
# 149 tests passed, 0 failed

python scripts/check-windows-footguns.py --diff upstream/main
# No Windows footguns found (3 files scanned)

git diff --check upstream/main...HEAD
# passed

The full-suite checkbox is intentionally unchecked. A local rerun of the two gateway repro files that had appeared during broader validation produced:

scripts/run_tests.sh tests/gateway/test_agent_cache.py tests/gateway/test_compression_concurrent_sessions.py
# tests/gateway/test_compression_concurrent_sessions.py: 2 passed
# tests/gateway/test_agent_cache.py: 62 passed, 1 failed

The remaining local failure is:

tests/gateway/test_agent_cache.py::TestExtractCacheBustingConfig::test_honcho_cache_busting_config_memoized_by_mtime

That assertion is in Honcho/gateway cache mtime handling and is outside this PR's Telegram command-menu config changes. I also reproduced the same tests/gateway/test_agent_cache.py failure on current upstream/main (c3055d618), so it is not introduced by this branch.

Screenshots / Logs

N/A — this changes Telegram BotCommand registration behavior and config/docs; no UI screenshot is needed.