feat: unfreeze TelegramBridgeConfig for hot-reload of voice, files, chat_ids, timing settings

[nathanschram]

Context

PR #285 (issue #269) implemented hot-reload for trigger configuration (crons/webhooks) via TriggerManager. During that work, we identified a second class of settings that could be hot-reloadable but are blocked by the frozen TelegramBridgeConfig dataclass.

Problem

TelegramBridgeConfig is defined as @dataclass(frozen=True, slots=True) in src/untether/telegram/bridge.py:134. This means all fields are immutable after construction. Several of these fields are already read per-message (correct pattern for hot-reload), but the frozen container prevents updating them when the TOML changes.

Settings blocked by frozen config

Setting	Field(s)	Read pattern	Effort
Allowed users	allowed_user_ids	Per-message in route_update()	Easy
Chat routing	chat_ids	Per-poll via _allowed_chat_ids()	Easy
Voice transcription	voice_transcription, voice_max_bytes, voice_transcription_model, voice_transcription_base_url, voice_transcription_api_key, voice_show_transcription	Per-message in voice handler	Easy
File transfer	files (TelegramFilesSettings)	Per-message in file handler	Easy
Message timing	forward_coalesce_s, media_group_debounce_s	Copied to state at startup	Easy — reference config instead
Resume line	show_resume_line	Per-message (already effectively reloadable via run_options)	Already done

Proposed approach

Option A: Unfreeze the dataclass

• Remove frozen=True from TelegramBridgeConfig
• Add an update_from() method that selectively updates reloadable fields
• Wire into handle_reload() in loop.py
• Pros: Simple, minimal code changes
• Cons: Loses immutability guarantees

Option B: Config wrapper / proxy

• Keep TelegramBridgeConfig frozen
• Create a LiveConfig wrapper that holds a mutable reference to the latest config
• Components read from wrapper instead of frozen config
• Pros: Keeps immutability for non-reloadable fields
• Cons: More indirection

Recommendation: Option A is simpler and sufficient. The fields that truly can't change (bot token, transport) are architectural constraints, not protected by frozen=True.

What remains restart-only (no fix possible)

• Bot token / chat ID — Telegram client connection
• Webhook server host/port — aiohttp binds once
• Transport type — entire transport stack
• session_mode (stateless ↔ chat) — requires state store init/teardown
• topics.enabled toggle — requires topic state store init
• New engine binaries — resolved via shutil.which() at startup

Related

• feat: hot-reload support for triggers, watchdog, and progress settings #269 — hot-reload trigger configuration (implemented in PR feat: hot-reload trigger config without restart #285)
• PR feat: hot-reload trigger config without restart #285 — TriggerManager for cron/webhook hot-reload

[nathanschram]

Implemented in v0.35.1rc4 — TelegramBridgeConfig unfrozen (slots preserved), gains update_from(settings) method wired into handle_reload(). 11 fields hot-reload; restart-only keys still warn. 11 tests in test_bridge_config_reload.py. See PR #292.

[nathanschram]

v0.35.1rc4 Implementation Status — Complete

Fully implemented in PR #292 (Option A from the issue: unfreeze the dataclass).

What shipped

• TelegramBridgeConfig changed from @dataclass(frozen=True, slots=True) to @dataclass(slots=True) — slots preserved for memory efficiency, frozen dropped for mutability
• New update_from(settings: TelegramTransportSettings) method copies 11 reloadable fields
• handle_reload() in loop.py now:
  • Separates RESTART_ONLY_KEYS (bot_token, chat_id, session_mode, topics, message_overflow) from hot-reloadable keys
  • Calls cfg.update_from() for any non-restart key changes
  • Refreshes TelegramLoopState.forward_coalesce_s and media_group_debounce_s caches
  • Logs config.reload.transport_config_hot_reloaded with changed key names
• route_update() now reads cfg.allowed_user_ids live via frozenset(cfg.allowed_user_ids) per update (was: snapshotted once at startup)
• trigger_manager: TriggerManager | None = None field added to bridge config (used by feat: trigger visibility — indicators, discovery, and run history #271 visibility)

Hot-reloadable fields (all 11)

voice_transcription, voice_max_bytes, voice_transcription_model, voice_transcription_base_url, voice_transcription_api_key, voice_show_transcription, forward_coalesce_s, media_group_debounce_s, allowed_user_ids, files (entire nested object), show_resume_line

Test coverage

• test_bridge_config_reload.py — 11 tests:
  • Unfrozen (direct assignment works, slots still prevent arbitrary attrs)
  • update_from() copies all 11 fields correctly
  • Nested files object is swapped (not mutated in-place)
  • Identity fields (bot, runtime, chat_id, exec_cfg, session_mode, topics) preserved after reload
  • voice_transcription_api_key removal → None
  • allowed_user_ids stored as tuple
  • trigger_manager field defaults to None and is post-construction assignable

[nathanschram]

Integration Test Results — v0.35.1rc4

Tested: 2026-04-14 against @untether_dev_bot (local editable source)
Branch: feature/v0.35.1rc4

Hot-reload bridge config (BR1–BR3) ✅

Test	Result	Details
BR1: Voice hot-reload (disable)	✅ PASS	Set voice_transcription = false in TOML → logs show config.reload.transport_config_hot_reloaded keys=['voice_transcription'] transport=telegram
BR2: Voice hot-reload (re-enable)	✅ PASS	Set voice_transcription = true → same transport_config_hot_reloaded log with keys=['voice_transcription']
BR3: Restart-only key warning	✅ PASS	Changed session_mode = "stateless" → logs show config.reload.transport_config_changed keys=['session_mode'] restart_required=True transport=telegram — correctly warns but does NOT apply the change

Verified capabilities

• TelegramBridgeConfig.update_from(): Correctly applies hot-reloadable fields from TelegramTransportSettings
• Hot-reloadable fields confirmed: voice_transcription changes take effect immediately without restart
• Restart-only fields protected: session_mode change emits warning with restart_required=True — the field is NOT applied until restart, preventing accidental mode changes
• handle_reload() integration: TelegramLoopState refreshes its two cached config copies on reload

Verdict: Bridge config hot-reload works correctly. Hot-reloadable fields apply immediately; restart-only fields warn safely. Ready for staging.

[nathanschram]

Fully implemented in v0.35.1rc4 (commit 678c3c4):

• TelegramBridgeConfig unfrozen (slots preserved)
• update_from(settings) copies all reloadable fields (voice_transcription, file transfer, allowed_user_ids, timing, show_resume_line)
• handle_reload() in loop.py wires update_from() into hot-reload path
• route_update() reads cfg.allowed_user_ids live so allowlist changes take effect on next message
• Restart-only keys (bot_token, chat_id, session_mode, topics, message_overflow) warn with restart_required=true
• 11 unit tests in test_bridge_config_reload.py

Closing as completed.