diff --git a/.env.example b/.env.example index 812986dca30..b7f3b008faf 100644 --- a/.env.example +++ b/.env.example @@ -339,6 +339,7 @@ BROWSER_INACTIVITY_TIMEOUT=120 # TELEGRAM_ALLOWED_USERS= # Comma-separated user IDs # TELEGRAM_HOME_CHANNEL= # Default chat for cron delivery # TELEGRAM_HOME_CHANNEL_NAME= # Display name for home channel +# TELEGRAM_CRON_THREAD_ID= # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode # Webhook mode (optional — for cloud deployments like Fly.io/Railway) # Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode. diff --git a/cron/scheduler.py b/cron/scheduler.py index be9bab41215..08221c6640a 100644 --- a/cron/scheduler.py +++ b/cron/scheduler.py @@ -292,10 +292,23 @@ def _get_home_target_chat_id(platform_name: str) -> str: def _get_home_target_thread_id(platform_name: str) -> Optional[str]: - """Return the optional thread/topic ID for a platform home target.""" + """Return the optional thread/topic ID for a platform home target. + + Telegram-only override: ``TELEGRAM_CRON_THREAD_ID`` takes precedence over + ``TELEGRAM_HOME_CHANNEL_THREAD_ID`` for cron delivery. When topic mode is + enabled, deliveries that land in the root DM (thread_id unset) end up in + the system-only lobby where the user cannot reply — the gateway returns + the lobby reminder and drops ``reply_to_message_id`` (#24409). Pointing + cron at a dedicated topic via this env var lets replies work as expected + without changing the lobby invariant. + """ env_var = _resolve_home_env_var(platform_name) if not env_var: return None + if platform_name.lower() == "telegram": + cron_thread = os.getenv("TELEGRAM_CRON_THREAD_ID", "").strip() + if cron_thread: + return cron_thread value = os.getenv(f"{env_var}_THREAD_ID", "").strip() if not value: legacy = _LEGACY_HOME_TARGET_ENV_VARS.get(env_var) diff --git a/tests/conftest.py b/tests/conftest.py index c799999b20f..a0446b88632 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -243,6 +243,7 @@ _HERMES_BEHAVIORAL_VARS = frozenset({ "TELEGRAM_HOME_CHANNEL", "TELEGRAM_HOME_CHANNEL_THREAD_ID", "TELEGRAM_HOME_CHANNEL_NAME", + "TELEGRAM_CRON_THREAD_ID", "DISCORD_HOME_CHANNEL", "DISCORD_HOME_CHANNEL_THREAD_ID", "DISCORD_HOME_CHANNEL_NAME", diff --git a/tests/cron/test_scheduler.py b/tests/cron/test_scheduler.py index bbb0343088e..473e7e98b44 100644 --- a/tests/cron/test_scheduler.py +++ b/tests/cron/test_scheduler.py @@ -151,6 +151,53 @@ class TestResolveDeliveryTarget: "thread_id": "topic-7", } + def test_telegram_cron_thread_id_overrides_home_thread_id(self, monkeypatch): + """TELEGRAM_CRON_THREAD_ID wins over TELEGRAM_HOME_CHANNEL_THREAD_ID for cron (#24409).""" + monkeypatch.setenv("TELEGRAM_HOME_CHANNEL", "-1001234567890") + monkeypatch.setenv("TELEGRAM_HOME_CHANNEL_THREAD_ID", "5") + monkeypatch.setenv("TELEGRAM_CRON_THREAD_ID", "42") + + assert _resolve_delivery_target({"deliver": "telegram"}) == { + "platform": "telegram", + "chat_id": "-1001234567890", + "thread_id": "42", + } + + def test_telegram_cron_thread_id_sets_thread_when_home_thread_unset(self, monkeypatch): + """TELEGRAM_CRON_THREAD_ID supplies a thread when no home thread is configured.""" + monkeypatch.setenv("TELEGRAM_HOME_CHANNEL", "-1001234567890") + monkeypatch.delenv("TELEGRAM_HOME_CHANNEL_THREAD_ID", raising=False) + monkeypatch.setenv("TELEGRAM_CRON_THREAD_ID", "42") + + assert _resolve_delivery_target({"deliver": "telegram"}) == { + "platform": "telegram", + "chat_id": "-1001234567890", + "thread_id": "42", + } + + def test_telegram_cron_thread_id_does_not_leak_to_other_platforms(self, monkeypatch): + """TELEGRAM_CRON_THREAD_ID is Telegram-only; other platforms keep their own thread resolution.""" + monkeypatch.setenv("DISCORD_HOME_CHANNEL", "parent-42") + monkeypatch.setenv("DISCORD_HOME_CHANNEL_THREAD_ID", "topic-7") + monkeypatch.setenv("TELEGRAM_CRON_THREAD_ID", "42") + + assert _resolve_delivery_target({"deliver": "discord"}) == { + "platform": "discord", + "chat_id": "parent-42", + "thread_id": "topic-7", + } + + def test_explicit_telegram_topic_target_overrides_cron_thread_id(self, monkeypatch): + """Explicit ``telegram:chat:thread`` targets bypass TELEGRAM_CRON_THREAD_ID.""" + monkeypatch.setenv("TELEGRAM_CRON_THREAD_ID", "999") + + job = {"deliver": "telegram:-1003724596514:17"} + assert _resolve_delivery_target(job) == { + "platform": "telegram", + "chat_id": "-1003724596514", + "thread_id": "17", + } + def test_explicit_telegram_topic_target_with_thread_id(self): """deliver: 'telegram:chat_id:thread_id' parses correctly.""" job = { diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index 8d7d4d398ee..6ecb42288ac 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -248,6 +248,7 @@ For cloud sandbox backends, persistence is filesystem-oriented. `TERMINAL_LIFETI | `TELEGRAM_GROUP_ALLOWED_CHATS` | Comma-separated group/forum chat IDs; any member is authorized | | `TELEGRAM_HOME_CHANNEL` | Default Telegram chat/channel for cron delivery | | `TELEGRAM_HOME_CHANNEL_NAME` | Display name for the Telegram home channel | +| `TELEGRAM_CRON_THREAD_ID` | Forum topic ID to receive cron deliveries; overrides `TELEGRAM_HOME_CHANNEL_THREAD_ID` for cron only. Use in topic mode so replies to cron messages open a new session instead of hitting the system lobby (#24409). | | `TELEGRAM_WEBHOOK_URL` | Public HTTPS URL for webhook mode (enables webhook instead of polling) | | `TELEGRAM_WEBHOOK_PORT` | Local listen port for webhook server (default: `8443`) | | `TELEGRAM_WEBHOOK_SECRET` | Secret token Telegram echoes back in each update for verification. **Required whenever `TELEGRAM_WEBHOOK_URL` is set** — the gateway refuses to start without it (GHSA-3vpc-7q5r-276h). Generate with `openssl rand -hex 32`. | diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md index 9772d433812..49af60c3503 100644 --- a/website/docs/user-guide/features/cron.md +++ b/website/docs/user-guide/features/cron.md @@ -258,6 +258,17 @@ Semantics: `all` expands to every platform with a configured home channel. Zero `all` composes with explicit targets. `origin,all` delivers to the origin chat *plus* every other connected home channel, de-duplicating by `(platform, chat_id, thread_id)`. +### Telegram cron topic (`TELEGRAM_CRON_THREAD_ID`) + +When Telegram topic mode is enabled, the root DM is reserved as a system lobby — replies sent there are rebuffed with a lobby reminder and `reply_to_message_id` is dropped, so you cannot reply to a cron message that landed in the main chat. + +Point cron at a dedicated forum topic instead: + +1. In Telegram, open the bot DM and create a topic named e.g. `Cron`. Long-press the topic header → **Copy link**; the trailing integer is the topic's `message_thread_id`. +2. Set `TELEGRAM_CRON_THREAD_ID=` in your `.env`. + +This applies only to cron deliveries. `TELEGRAM_HOME_CHANNEL_THREAD_ID` (used elsewhere, e.g. restart notifications) is unchanged. Explicit `deliver="telegram:chat_id:thread_id"` targets continue to win over the env var. Replies to cron messages now arrive in the existing topic session, so you can act on them directly. + ### Response wrapping By default, delivered cron output is wrapped with a header and footer so the recipient knows it came from a scheduled task: diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md index 056637e6238..65ebf00889f 100644 --- a/website/docs/user-guide/messaging/telegram.md +++ b/website/docs/user-guide/messaging/telegram.md @@ -256,6 +256,16 @@ TELEGRAM_HOME_CHANNEL_NAME="My Notes" Group chat IDs are negative numbers (e.g., `-1001234567890`). Your personal DM chat ID is the same as your user ID. ::: +### Cron deliveries in topic mode + +If you have topic mode enabled in your bot DM, cron messages delivered to the root chat land in the system-only lobby — replying there opens no session and you see the "main chat is reserved for system commands" notice. Create a dedicated forum topic (e.g. `Cron`) and set: + +```bash +TELEGRAM_CRON_THREAD_ID= +``` + +`TELEGRAM_CRON_THREAD_ID` overrides `TELEGRAM_HOME_CHANNEL_THREAD_ID` for cron deliveries only. Replies in that topic continue the topic's existing session. + ## Voice Messages ### Incoming Voice (Speech-to-Text)