hermes-agent/website/docs/user-guide
teknium1 1381c89e56 fix(telegram): polish topic mode — CASCADE, General-topic handling, rename guard, debounce
Five follow-ups to topic mode based on integration audit:

1. ON DELETE CASCADE on telegram_dm_topic_bindings.session_id. Session
   pruning (manual /delete, auto-cleanup, any future prune job) would
   have thrown 'FOREIGN KEY constraint failed' for sessions bound to a
   topic. Migration bumped to v2, rebuilds the bindings table in place
   if FK lacks CASCADE. Idempotent; only runs once per DB.

2. Never auto-rename operator-declared topics. If an operator has
   extra.dm_topics configured AND a user runs /topic, messages in those
   pre-declared topics would previously trigger auto-rename and silently
   mutate operator config. _rename_telegram_topic_for_session_title now
   early-returns when _get_dm_topic_info returns a dict for this
   (chat_id, thread_id). Uses class-based lookup (not hasattr) so
   MagicMock test fixtures don't accidentally trip the guard.

3. General topic handling. Telegram's General (pinned top) topic in a
   forum-enabled private chat may send messages with message_thread_id=1
   or omit thread_id entirely depending on client. Both are now treated
   as the root lobby, not a topic lane. Prevents users from
   accidentally burning a session on the General topic.

4. Debounce the root-lobby reminder. 30-second cooldown per chat so a
   user who forgets topic mode is enabled and types ten messages in the
   root gets one reminder, not ten. Explicit command replies
   (/new-in-lobby, /topic <session-id>) still land every time.

5. Docs: added under-the-hood invariants for the above, plus a
   Downgrade section explaining that rolling back to a pre-/topic
   Hermes build leaves the DB tables orphaned but harmless — DMs just
   revert to native per-thread isolation.

Tests:
- test_operator_declared_topic_is_not_auto_renamed
- test_general_topic_is_treated_as_root_lobby
- test_lobby_reminder_is_debounced_per_chat
- test_binding_survives_session_deletion_via_cascade
- test_migration_rebuilds_v1_binding_table_with_cascade_fk

Validated: 4803/4804 tests pass (tests/gateway/ + tests/test_hermes_state.py).
Sole failure is a pre-existing test_teams::test_send_typing flake
unrelated to this PR.
2026-05-04 12:07:17 -07:00
..
features docs: default custom tool creation to plugins 2026-05-04 05:53:16 -07:00
messaging fix(telegram): polish topic mode — CASCADE, General-topic handling, rename guard, debounce 2026-05-04 12:07:17 -07:00
skills docs(sidebar): collapse exploding skills tree to a single Skills node (#18259) 2026-04-30 23:08:22 -07:00
_category_.json feat: add documentation website (Docusaurus) 2026-03-05 05:24:55 -08:00
checkpoints-and-rollback.md docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) 2026-04-29 20:55:59 -07:00
cli.md docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) 2026-04-29 20:55:59 -07:00
configuration.md fix(cli): local backend CLI always uses launch directory, stops .env sync of TERMINAL_CWD (#19334) 2026-05-04 11:36:19 +05:30
configuring-models.md feat(dashboard): configure main + auxiliary models from Models page (#17802) 2026-04-29 23:53:12 -07:00
docker.md feat(docker): launch dashboard as side-process via HERMES_DASHBOARD=1 2026-05-04 15:37:27 +10:00
git-worktrees.md docs: restructure site navigation — promote features and platforms to top-level (#4116) 2026-03-30 18:39:51 -07:00
profiles.md Revert "fix(cli): CLI/TUI on local backend always uses launch directory, ignores terminal.cwd (#19242)" (#19329) 2026-05-04 00:43:58 +05:30
security.md docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) 2026-04-29 20:55:59 -07:00
sessions.md docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) 2026-04-29 20:55:59 -07:00
tui.md docs: two-week gap sweep — platforms, CLI, config, TUI, hooks, providers (#17727) 2026-04-29 20:32:37 -07:00