hermes-agent/gateway/run_topics.py
Teknium 9bcbe7b5df
feat(i18n): pluggable, layered language packs across core, Desktop and TUI (#126296)
* feat(i18n): layered catalogs — plugin packs and user overlay over bundled locales

* feat(tui): i18n layer — en catalog, nanostore runtime, RPC pack loader, _keys.tui.json emitter

ui-tui/src/i18n/: en.ts (facade over topical siblings under en/), types.ts
(Translations + dotted TranslationKey derived from en), runtime.ts ($locale/
$catalog atoms, translateFrom active→en→key, pack merge with string→fn
wrapping for {0}/{1} placeholders), loader.ts (display.language →
i18n.catalog {lang, surface:'tui'}, English when the method is missing),
useT()/useLocale() hooks, t() for non-React code. useConfigSync feeds the
loader from the existing config.get full hydration. `npm run i18n:keys`
writes locales/_keys.tui.json (sorted flat key list) and runs before build.

* feat(plugins): provides_locales manifest field, ctx.register_locale/register_locale_dir, manifest-only language packs

* chore(tui): split en catalog siblings by lane (slash sibling)

* feat(plugins): validate language packs — parse, text-only, key-subset WARN against en / _keys exports

* feat(tui_gateway): i18n.languages / i18n.catalog RPC + regenerated contracts

* feat(config): display.language accepts any supported_languages() id, refuses unknown ids with the list

* docs(i18n): language packs user guide, pluggable display.language, plugin developer section, AGENTS notes

* feat(plugins): report language-pack layers in the mid-run activation summary

* feat(tui): wire status bar, composer placeholders, hotkey help and approval/clarify/confirm prompts through i18n

StatusRule maps compared state values (ready/running…/summoning) to catalog
text at render via displayStatus(); hotkeys()/placeholder() resolve lazily so
a pack that arrives after boot applies. Catalog grows to 81 keys.

* feat(desktop): pluggable app locales — registry, host.i18n.registerAppLocale, backend packs, keys emitter

- Locale widens to string (BundledLocale keeps the union); TRANSLATIONS stays
  the bundled record and every consumer resolves through the registry.
- src/i18n/registry.ts: registerAppLocale(id, {endonym, rtl, translations})
  layers partial packs (nested or flat dotted) over bundled/en via
  mergeTranslations; a string over a function-valued en entry becomes a
  positional {0}/{1} formatter; $appLocaleVersion bumps so translators
  re-render; per-source disposers + replaceAppLocaleSource for atomic swaps.
- Backend packs: i18n.languages + i18n.catalog {surface:'desktop'} feed the
  registry as source 'backend' (method-not-found is silent); re-synced on
  socket open, display.language change and profile switch. A saved pack-only
  language is promoted once its pack registers.
- SDK: host.i18n.registerAppLocale / languageOptions; ctx.i18n.registerAppLocale
  tracked for unload. Docs in the desktop plugin SDK guide + skill reference.
- Language switcher lists bundled ∪ registered ∪ backend, endonym-only; RTL
  from the registry (applyDocumentLocale takes rtl).
- npm run i18n:keys emits locales/_keys.desktop.json (wired into build).

* i18n(cli): route /topup + /subscription copy through t() (cli.billing.*, cli.subscription.*)

Module-level copy tables and modal choice tuples in cli_billing_mixin.py froze
English at import, before display.language was known. They are now key tables /
builder functions evaluated at call time; every user-facing line in the /usage
balance block, /subscription and the five /topup screens reads the catalog.
Choice VALUES stay English identifiers. Fragment-assembled status lines
(Plan: … → cancels · $x left · renews …) become full templates.

* i18n(gateway): exec-approval card contract + base/run/run_busy/run_inbound replies through t()

- base_exec_approval: EA_* English constants stay; add ea_header_text()/ea_reason_label_text()/
  ea_smart_deny_line_text()/ea_default_reason_text()/ea_action_labels()/approval_timed_out_notice()
  accessors; deadline + timed-out notice resolve via gateway.exec_approval.*
- BasePlatformAdapter._EA_HEADER/_EA_REASON_LABEL/_EA_SMART_DENY_LINE/_EA_ACTION_LABELS become
  properties (adapters still shadow them with markup class attrs)
- run.py: provider error replies table holds catalog keys; _CONTEXT_OVERFLOW_REPLY -> _context_overflow_reply()
- run_busy/run_inbound: typed approval + slash-confirm matchers accept English ∪ approval.inputs.* (t())
- locales/en.yaml: gateway.exec_approval/busy/errors/... namespaces

* i18n(cli): wire modal, loops, agent-setup mixins through t() (cli.* keys)

* i18n(platforms): route Slack, Matrix and Feishu user-facing text through t()

Exec-approval markup overrides (_EA_HEADER/_EA_REASON_LABEL/_EA_SMART_DENY_LINE/
_EA_ACTION_LABELS) become per-call properties over the shared
gateway.exec_approval.* contract keys, so Slack's 3000-char section budget
measures the resolved template. Slack _APPROVAL_DECISIONS/_CONFIRM_DECISIONS,
Feishu _APPROVAL_LABEL_MAP and Matrix _EA_LEGEND/_EA_TYPED_HINT turn into
key tables resolved at click time; the Matrix typed hints become whole
sentences per offered tier instead of spliced fragments. Slack button labels
are cut to 75 chars and select placeholders to 150 after translation; the
model-facing clarify fallback answer ('choice N') stays English while the
card copy localizes.

locales/en.yaml gains the gateway.exec_approval.* contract keys plus the
platform.shared.* / platform.slack.* / platform.matrix.* / platform.feishu.*
namespaces (and the keys for the other adapters wired in follow-up commits).

* i18n(gateway): run_turn / run_turn_runner / approval-settle copy through t()

- status hints, proxy errors, background task notices, progress heartbeats, session info lines
- tool progress chrome (tool_head/tool_pending/tool_preview/tool_verbose) shared by base.format_tool_event
- run_turn_runner:1406 Chinese clarify placeholder -> gateway.clarify.native_stream_placeholder (zh text kept in zh.yaml)
- _UNEXPECTED_SILENCE_REPLY/_CLARIFY_EXPIRED_NOTICE -> accessor functions

* i18n(platforms): route Google Chat and Teams user-facing text through t()

Google Chat clarify card, typing placeholder, orphan-card labels and the whole
/setup-files reply set (module constants become platform.google_chat.setup_files.*
keys resolved at reply time). The attachment-fallback notice that shipped
hardcoded in Spanish is keyed with an English en value; es.yaml carries the
original Spanish text for those four keys.

Teams approval card header/reason use the gateway.exec_approval.* contract,
_APPROVAL_LABELS becomes a key table resolved at click time, and the meeting
summary writer resolves its section headings/fallbacks per render.

* i18n(platforms): route LINE, WeCom, email, DingTalk, IRC and Home Assistant text through t()

LINE default copy constants become catalog keys resolved in __init__ (the
LINE_*_TEXT / extra.* operator overrides still win); the busy-ack bypass
matcher keys on the leading emoji marker only, so it keeps firing once the
gateway busy heads are localized. WeCom media size/format notices that shipped
hardcoded in Chinese are keyed with English en values and zh.yaml carries the
original Chinese text. DingTalk emotion bubbles resolve per send.

* i18n(cli): route /model switch output and -q status lines through t() (cli.model.*, cli.single_query.*)

Switch-summary labels shared with the gateway reuse gateway.model.* keys
(provider/context/max-output/capabilities/prompt-caching); CLI-only variants
(glyph or no-backtick forms) live under cli.model.*. The hand-padded /model usage
block becomes a (form, description-key) table padded at render time so the
command syntax stays fixed while descriptions translate. -q 'Error:' reuses
gateway.model.error_prefix.

* i18n(cli): route TUI panel/hint/placeholder copy through t() (cli.tui.*)

_APPROVAL_CHOICE_LABELS and _TUI_MODAL_HINTS become key tables resolved at
render time; vault/sudo panel bodies are one catalog value per panel split on
newline; inline plurals use <key>_one/<key>_other. Adds the cli.* namespace
(shared/tui/voice/render/subagents/dock) to locales/en.yaml.

* i18n(cli): voice/wake-word CLI copy through t() (cli.voice.*)

RuntimeError texts raised in _voice_start_recording are human copy (callers
print {e}) and are keyed; the Termux requirement-check match stays English.
Wake state ids stay internal, only their labels localize.

* i18n(cli): live-work dock, subagent monitor and render copy through t()

cli.subagents.* / cli.dock.* / cli.render.*; count fragments pluralize via
_one/_other keys, verdict table holds keys resolved at paint time so width
clipping measures the translated text.

* i18n(gateway): unauthorized/pairing, voice, topics, shutdown, startup, notifications, kanban pings through t()

* i18n(cli): move tips + composer placeholders into the catalog (tips.tNNN / tips.placeholder.pNN)

get_random_tip()/get_random_composer_placeholder() pick a key from the English catalog
(the parity baseline, probed once per process) and resolve it through t() for the active
language, so language packs translate tips like any other string. Also lands the cli.*
en.yaml namespace consumed by the CLI info/help/error-copy wiring in the next commit.

* i18n(cli): wire chat-turn + session mixins through t(); kanban log trimmer matches t() output

* test(cli): assert TUI/dock/voice copy via t(key); prove labels resolve at render time

Pinned-English assertions in the approval-UI, live-work dock and voice tests now
go through the catalog. New test swaps the catalog after import and checks the
approval panel + hint row follow it (the reason _APPROVAL_CHOICE_LABELS and
_TUI_MODAL_HINTS became key tables).

* i18n(cli): route CLI info/help/error copy through t() (cli.* namespace)

cli_info_mixin: /help consumes CommandDef.describe() (added to commands.py: slash.<name>.description
with fallback to .description), section titles/skill/quick-command headers, /tools, /toolsets,
/usage labels, /context, /whoami, /insights, /gateway status, tool-progress labels, bang-shell
denials, MCP config-watch + /reload-mcp confirm/reload lines, /reload-skills, and the session-store
warning all read the catalog at call time (module-level label tables became functions so the
active language is honoured after startup). cli.py: worktree cleanup, tirith warning, show_config
(labels re-padded at print time), quick/plugin/skill slash-command errors, ambiguous-command hint,
stdin error, gateway start, profile warning. cli_chat_error_copy / cli_unknown_command /
cli_output / cli_init_mixin: chat error panel copy, did-you-mean lines, n-more / yes-no prompt
(localized affirmative initial alongside 'y'), unknown-toolsets warning.

* i18n(w1a): wire agent display/explainers/approval + slash registry/help through t()

- hermes_cli/commands.py: CommandDef.describe() resolves slash.<name>.description
  at call time; category labels via slash.category.*; help/alias/usage suffixes
  via slash.shared.*; gateway_help_lines and commands_platforms/slash_exec use them.
- agent/display.py: display.verb.* resolved at call time via get_tool_verb();
  bridge/spinner/thinking-verb/cute-row/failure/preview/diff text via display.*.
- agent/turn_explainers.py: exit-reason / persistence-cause tables become call-time
  lookups (explainer.exit.*, explainer.persistence.*, explainer.file_mutation.*).
- agent/background_review.py, session_activity.py, context_breakdown.py,
  status_output.py: review summaries, iteration progress, context notices.
- tools/approval.py, approval_context.py: approval.summary.*, approval.noun.*,
  approval.window.* pluralized keys.
- gateway/slash_commands*.py: remaining raw strings (busy, whoami, platform,
  bundles, memory, skills, approvals, set_home, diff, update, debug, profile,
  heartbeat, refine, review, subgoal, loop, retry, compress codex path, save,
  sessions, model guard/errors, agents rows, topup, login). HISTORY_UNREADABLE
  keeps its English constant; callers use history_unreadable() ->
  gateway.shared.history_unreadable.
- locales/en.yaml: new approval/display/explainer/slash blocks + gateway leftovers.

* i18n(telegram): route adapter chat copy through t()

Approval card (header/reason/smart-deny as HTML-escaped properties), inline
button labels, callback toasts (cut at Telegram's 200-char cap), model/choice
pickers, clarify/update/slash-confirm prompts, gmail-triage labels and the
inbound-media failure notice now come from the catalog. _UNAUTHORIZED is a
lazy _unauthorized() so the import no longer binds a language. The command
menu carries a language+payload fingerprint (forum scopes re-register on
change) and BotCommand descriptions are cut at 256.

Adds gateway.exec_approval.* (WAVE2 contract), platform.telegram.*,
platform.discord.* and the slash.*.description keys the Discord table shares
with the CLI registry to locales/en.yaml.

* i18n(gateway/platforms): whatsapp_cloud, yuanbao, weixin, signal, api_server copy through t()

- whatsapp_cloud: clarify list/buttons, approve/deny + slash-confirm labels via platform.whatsapp.* (t()-then-truncate at 20/24/72 caps); _EA_HEADER becomes a property wrapping ea_header_text()
- yuanbao: SLOW_RESPONSE_MESSAGE -> slow_response_message() (platform.yuanbao.slow_response_notice; zh keeps the original text); cron-wrapper markers centralized as module constants for strip_cron_wrapper
- api_server: PROVIDER_AUTH_FAILED_LABEL/PROVIDER_RATE_LIMITED_LABEL stay English for run.py matchers; user_text() renders via t()
- signal/_format_wait, weixin voice caption, openai_routes transformed notice
- run_turn: second _UNEXPECTED_SILENCE_REPLY consumer -> accessor

* i18n(discord): route adapter chat copy through t()

Native slash-command table becomes _NATIVE_SLASH_COMMAND_SPECS holding catalog
keys; _native_slash_commands() resolves descriptions, parameter descriptions
and Choice names for the active language, each cut at Discord's 100-char cap,
and the app-command sync fingerprint now includes get_language() so a
display.language change re-syncs. Exec-approval card (gateway.exec_approval.*
contract), slash-confirm / clarify / update views, model+choice pickers,
thread creation, forum titles, voice acks, the response-truncation notice,
the unauthorized-slash security alert and the media upload-size notices all
read from platform.discord.*. Decorator-declared button labels are relabelled
in __init__ (80-char cap); embed titles cut at 256, select placeholders at
150, option label/description at 100. _UNAUTHORIZED is a lazy _unauthorized().

* i18n(cli): wire status-bar, stream, terminal mixins + terminal_input through t(); rename kwargs that shadow t(key)

* i18n: wire hermes_cli/cli_commands_mixin.py slash-command copy through t()

- 431 new leaves under cli.commands.<cmd>.* in locales/en.yaml; 12 rows reuse
  existing gateway.* keys (rollback, diff, resume, branch, btw, model, reasoning)
  via a _gt() helper so CLI and gateway replies stay identical.
- Module-level English tables (_BUSY_MODE_*, _REASONING_TOGGLES, _HATCH_PROGRESS,
  _DIFF_LABELS, _LOCAL_ENGINE_LINES) become call-time catalog lookups keyed by id.
- Verb tables (Enabling/Disabling, Paused/Resumed/Triggered, planned/done,
  Updating/Generating) are one full template per variant; plurals use
  <key>_one/<key>_other via _tn(); hand-padded column labels (/snapshot list)
  translate the value and re-pad at the call site.
- Multi-line usage blocks are single catalog values split with _lines().
- Model-facing system notes and DB-stored reasons stay English (EXCLUDED).

* tests: assert /handoff, /worktree, /login CLI copy via t(key) instead of pinned English

* test(i18n): pin Telegram/Discord adapter catalog wiring

Lazy unauthorized notice, exec-approval contract keys, HTML escaping before
Telegram <b> wrapping, 200-char toast / 256-char BotCommand caps, Discord
100-char app-command text and 80-char button caps, and language-bearing
command-menu fingerprints on both platforms.

* i18n: reconcile cli.shared on/off vs enabled/disabled after lane merge

* i18n: describe() in TUI-gateway slash listings; localize TUI exit resume hint

* i18n(tr): translate bundled catalog + tui pack

* i18n(ja): translate bundled catalog + tui pack

* i18n(ko): translate bundled catalog + tui pack

* i18n(zh): translate bundled catalog + tui pack

* i18n(fr): translate bundled catalog + tui pack

* i18n(af): translate bundled catalog + tui pack

* i18n(uk): translate bundled catalog + tui pack

* i18n(ar): translate bundled catalog + tui pack

* i18n(pt): translate bundled catalog + tui pack

* i18n(it): translate bundled catalog + tui pack

* i18n(es): translate bundled catalog + tui pack

* i18n(zh-hant): translate bundled catalog + tui pack

* i18n(ru): translate bundled catalog + tui pack

* i18n(hu): translate bundled catalog + tui pack

* i18n(hu): translate pre-existing English-valued leftovers (kanban wake, /context, /status, fast labels)

* i18n(de): translate bundled catalog + tui pack

* i18n(ga): translate bundled catalog + tui pack

* test(i18n): fixture matches _normalize_lang(lang, home) signature

* i18n(tui): scaffold userMessages/slashCmd en siblings

* i18n(tui): wire secure prompts + content tables

* feat(tui): i18n — wire billing, subscription, connection-setup and journey overlays

Adds en siblings billing.ts / subscription.ts / connection.ts (namespaces
billing, subscription, connection, journey) and routes every user-facing
literal in billingOverlay, subscriptionOverlay, connectionSetupOverlay and
journey through useT()/messages(). Module-level label tables became lazy
(scopeStillDeniedResult(), verbOf(T, action)); auto-reload rows dispatch on
stable ids instead of label text. Regenerates locales/_keys.tui.json.

* i18n(tui): wire slash ops/wake replies

* i18n(tui): wire pickers (modelPicker, activeSessionSwitcher, petPicker)

* i18n(tui): wire slash core/debug/setup replies

* i18n(tui): wire hubs (agents overlay/panel/controls, skills, plugins)

* i18n(tui): wire slash session/topup/subscription replies

* i18n(tui): wire chat bits (branding, thinking, messageLine, loaders, todo, queued, banner, entry)

* i18n(tui): register t3 siblings (pickers, hubs, secure, content, chatBits) and regenerate keys

* i18n(tui): wire userMessages copy through the userMessages namespace

* i18n(tui): lazy-copy test for userMessages, regenerate _keys.tui.json

* i18n(tui): wire session/gateway/lib text through the TUI catalog (lane t2)

Adds en siblings session.ts, gatewayMsg.ts, libText.ts (namespaces session,
gatewayMsg, libText) and routes user-facing literals in app/{useMainApp,
useSessionLifecycle,useInputHandlers,turnController,createServerRequestHandler,
setupHandoff,createGatewayEventHandler}.ts, gatewayClient displayed reasons,
lib/*, domain/*, hooks/* through t()/messages(). Status-bar state values that
code compares against, backend-matched strings, log lines, model-bound text,
and machine 'error:' prefixes stay literal. Regenerates locales/_keys.tui.json
(232 keys).

* i18n: serve bundled locales/<lang>.tui.yaml under overlay/packs; TUI pack parity test; regen _keys.tui.json (1250)

* i18n: translate pre-existing English stubs in bundled locales (424 leaves, 14 locales)

* tui: i18n-export-en script (English templates for pack translators)

* docs(i18n): bundled TUI packs are the bottom layer of the tui surface

* i18n(ru): translate TUI pack

* i18n(ar): translate TUI pack

* i18n(es): translate TUI pack

* i18n(pt): translate TUI pack

* i18n(ko): translate TUI pack

* i18n(de): translate TUI pack

* i18n(ja): translate TUI pack

* i18n(fr): translate TUI pack

* i18n(tr): translate TUI pack

* i18n(it): translate TUI pack

* i18n(zh): translate TUI pack

* i18n(zh-hant): translate TUI pack

* i18n(hu): translate TUI pack

* i18n(uk): translate TUI pack

1,169 missing keys translated; 81 pre-existing kept byte-identical. Parity OK missing=0 extra=0 placeholder_mismatch=0 empty=0.

Deliberately identical to en: chatBits.branding.mcpSummary ({0} MCP), chatBits.thinking.agentsHint ((/agents)), session.main.voiceStt (◉ STT), session.main.voiceTtsSuffix ( [tts]), slashCmd.core.help.tuiSection (TUI), slashCmd.core.history.hermesTag (Hermes #{0}), slashCmd.debug.heapdump.heapPath (heapdump: {0}), slashCmd.debug.mem.rss (rss), subscription.stepUp.title (Remote Spending — product feature name, as in core catalog), content.faces.* (glyph-only kaomoji).

* i18n(ga): translate TUI pack

* i18n(af): translate TUI pack

* plugin_guard: locale catalogs in language packs step down the agent-config family

A translated status line such as "Updating AGENTS.md" in locales/<lang>.yaml is UI text the loader
reads as a string leaf; it cannot edit a file. The bundled en.yaml itself tripped agent_config_mod
at critical, making any faithful language pack uninstallable. Injection shapes keep full severity.

* plugin_validate_locales: read key exports with utf-8-sig (Windows footgun lint)

* i18n(relay): route relay adapter prompt copy through t(); drop dead import-bound approval header

Adds platform.relay.* (5 keys) to en and all 16 bundled locales, reusing the sibling platform
translations for the confirm buttons and the Other option.

* ci: fix TUI import order, MDX table pipe, main's overflow-warning wording in all locales; fresh-install fixture carries the i18n kernel

- ui-tui/src/i18n/en.ts: perfectionist/sort-imports (slash before slashCmd)
- docs plugins/index.md: escape the | inside the provides_locales table cell (MDX parsed <id> as JSX)
- display.notice.uncompressed_context_overflow: adopt main's wording (names compression.enabled: false
  and /compact) in en + 16 locales; the guardrail test pins that phrase
- tests/scripts/test_fresh_source_install.py: the installer tail now resolves CLI text through
  agent.i18n, so the fixture tree carries the i18n kernel + en.yaml (not the agent runtime)

* docs(desktop-plugin-sdk): double-backtick the template-literal example (MDX evaluated ${n})

* test(e2e): display.language is validated against the live language set; exclude it from the arbitrary-string set property

* commands: keep the localized COMMANDS/COMMANDS_BY_CATEGORY module __getattr__ after the compat block removal

* build: never write locales/_keys.*.json from the desktop/TUI builds; regenerate the committed desktop key export

The desktop build regenerated locales/_keys.desktop.json in the checkout, so a
hermes update that rebuilt the app left the tree dirty (Desktop update E2E:
'M locales/_keys.desktop.json'). The key exports are committed artifacts pinned
to en.ts by apps/desktop/scripts/i18n-keys.test.mjs and ui-tui i18n:keys:check;
builds read them, never write them. Regenerated after main's new desktop strings.

* test: unbreak two main-red timing tests the PR merge-ref inherits

- test_local_runtime racing fake publishes the modern state record (legacy pid-only
  records are rejected since 65ff3ad353; main has been red on this test since)
- test_run_progress_topics ManyProgressLinesAgent waits for the first bubble instead of
  a fixed 0.35s, which a loaded CI runner does not always meet

* chore(i18n): regenerate desktop key catalog for main's new strings (model pricing, copy changelog)

* test(e2e): torture-chamber fd monitor confirms a deleted sidecar is still held before calling it a leak

SQLite's WAL last-close unlinks -shm before closing its descriptor (unixShmUnmap, then
unixShmPurge), so a healthy close shows a (deleted) -shm for microseconds; the 20ms poll
occasionally caught that window on the short-lived opener and failed the episode.

* chore(i18n): regenerate desktop key catalog for main's telemetry/consent strings

* chore(i18n): regenerate desktop key catalog after main sync

---------

Co-authored-by: Teknium <[email protected]>
2026-09-28 14:16:18 -07:00

603 lines
33 KiB
Python

"""Telegram forum-topic and Discord auto-thread binding/rename methods for GatewayRunner (MRO mixin).
``gateway.run`` internals are imported lazily inside method bodies (import cycle), so
``patch("gateway.run.X")`` keeps intercepting them at call time."""
from __future__ import annotations
import asyncio
import logging
import re
import time
from contextlib import suppress
from pathlib import Path
from typing import TYPE_CHECKING, Optional, Tuple
from agent.compaction_display import project_compaction_message_for_display
from agent.i18n import t
from gateway.config import Platform
from gateway.platforms.base import _prefix_within_utf16_limit, utf16_len
from gateway.platforms.event import MessageEvent
from gateway.session import SessionSource
from utils import is_truthy_value
if TYPE_CHECKING: # string annotations only; never imported at runtime (cycle)
from gateway.run import GatewayRunner # noqa: F401
from gateway.run_turn_runner import TurnRunner # noqa: F401
# Log-record parity with the origin module.
logger = logging.getLogger("gateway.run")
def _topic_restore_steps() -> tuple:
return (t("gateway.topic.restore_step_1"), t("gateway.topic.restore_step_2"))
def _collapse_title(title: str) -> str:
return re.sub(r"\s+", " ", str(title or "")).strip() or t("gateway.topic.default_title")
class GatewayTopicThreadsMixin:
"""Telegram forum-topic and Discord auto-thread binding/rename methods for GatewayRunner."""
# ── Telegram topic mode: predicates and keys ────────────────────────────────────────────
@staticmethod
def _telegram_topic_profile_name(source: SessionSource) -> str:
"""Profile namespace for topic-mode rows: the profile stamped on the routed event, never the
process-global one (under multiplex that mis-attributes state across bots sharing state.db).
See #76423.
"""
return str(getattr(source, "profile", None) or "").strip() or "default"
def _sync_session_db(self):
"""The sync SessionDB handle, or None. Only for callers that provably run off-loop."""
session_db = getattr(self, "_session_db", None)
return None if session_db is None else getattr(session_db, "_db", session_db)
@staticmethod
def _is_telegram_dm(source: SessionSource) -> bool:
return source.platform == Platform.TELEGRAM and source.chat_type == "dm"
def _telegram_topic_mode_enabled(self, source: SessionSource) -> bool:
"""Return whether Telegram DM topic mode is active for this chat."""
session_db = self._sync_session_db() if self._is_telegram_dm(source) else None
if session_db is None:
return False
try:
raw = session_db.is_telegram_topic_mode_enabled(
chat_id=str(source.chat_id), user_id=str(source.user_id),
profile_name=self._telegram_topic_profile_name(source),
)
except Exception:
logger.debug("Failed to read Telegram topic mode state", exc_info=True)
return False
# Only a real True enables topic mode; anything else (including MagicMock from test
# fixtures that didn't opt in) means off for this chat.
return raw is True
def _is_telegram_topic_root_lobby(self, source: SessionSource) -> bool:
"""True for the main Telegram DM (or General topic) when topic mode has made it a lobby."""
return (
self._is_telegram_dm(source) and self._telegram_topic_mode_enabled(source)
and str(source.thread_id or "") in self._TELEGRAM_GENERAL_TOPIC_IDS
)
def _is_telegram_topic_lane(self, source: SessionSource) -> bool:
"""True for a user-created Telegram private-chat topic lane."""
tid = str(source.thread_id or "")
return (
self._is_telegram_dm(source) and self._telegram_topic_mode_enabled(source)
and bool(tid) and tid not in self._TELEGRAM_GENERAL_TOPIC_IDS
)
def _telegram_topic_cooldown_key(self, source: SessionSource) -> Optional[str]:
"""Cooldown key (profile, chat_id): profiles sharing a Telegram private chat_id under
multiplex must not suppress each other's lobby reminders / capability hints.
See #76423.
"""
chat_id = str(source.chat_id or "")
return f"{self._telegram_topic_profile_name(source)}:{chat_id}" if chat_id else None
def _telegram_cooldown_elapsed(self, source: SessionSource, attr: str, cooldown_s: float) -> bool:
"""Per-(profile, chat) debounce: True (and stamp now) when the window has elapsed."""
if not hasattr(self, attr):
setattr(self, attr, {})
key = self._telegram_topic_cooldown_key(source)
if not key:
return True
stamps, now = getattr(self, attr), time.monotonic()
if now - stamps.get(key, 0.0) < cooldown_s:
return False
stamps[key] = now
return True
def _should_send_telegram_lobby_reminder(self, source: SessionSource) -> bool:
"""Rate-limit root-DM lobby reminders to one per cooldown window, not one per prompt typed."""
return self._telegram_cooldown_elapsed(source, "_telegram_lobby_reminder_ts", self._TELEGRAM_LOBBY_REMINDER_COOLDOWN_S)
def _should_send_telegram_capability_hint(self, source: SessionSource) -> bool:
"""Rate-limit the BotFather Threads Settings screenshot (repeated /topic must not re-upload it)."""
return self._telegram_cooldown_elapsed(source, "_telegram_capability_hint_ts", self._TELEGRAM_CAPABILITY_HINT_COOLDOWN_S)
# ── Telegram topic mode: user-facing text ───────────────────────────────────────────────
def _telegram_topic_root_lobby_message(self) -> str:
return t("gateway.topic.root_lobby")
def _telegram_topic_root_new_message(self) -> str:
return t("gateway.topic.root_new")
def _telegram_topic_new_header(self, source: SessionSource) -> Optional[str]:
return t("gateway.topic.new_header") if self._is_telegram_topic_lane(source) else None
def _telegram_topic_help_text(self) -> str:
return t("gateway.topic.help")
# ── Telegram topic bindings ─────────────────────────────────────────────────────────────
def _record_telegram_topic_binding(self, source: SessionSource, session_entry) -> None:
"""Persist the Telegram topic -> Hermes session binding for topic lanes (off-loop)."""
session_db = self._sync_session_db()
if session_db is None or not source.chat_id or not source.thread_id:
return
session_db.bind_telegram_topic(
chat_id=str(source.chat_id), thread_id=str(source.thread_id), user_id=str(source.user_id or ""),
session_key=session_entry.session_key, session_id=session_entry.session_id,
profile_name=self._telegram_topic_profile_name(source),
)
def _sync_telegram_topic_binding(self, source: SessionSource, session_entry, *, reason: str) -> None:
"""Update the topic binding to ``session_entry.session_id``: a stale binding after a mid-turn
compression rotation reloads the oversized parent next message, retriggering compression.
Telegram topic lanes persist a (chat_id, thread_id) -> session_id row so reopening a topic in a
fresh process resumes the right Hermes session. See #20470, #29712, #33414.
"""
if not self._is_telegram_topic_lane(source):
return
try:
self._record_telegram_topic_binding(source, session_entry)
except Exception:
logger.debug("telegram topic binding refresh failed (%s)", reason, exc_info=True)
def _recover_telegram_topic_thread_id(self, source: SessionSource) -> Optional[str]:
"""Pin lobby-shaped topic-mode DM replies (missing ``message_thread_id`` or General) to the
user's most-recent bound topic. Never rewrite a non-lobby, unbound thread id: a brand-new DM
topic is also "unknown" until its first message is recorded. None = leave the source alone."""
if (
not self._is_telegram_dm(source) or not source.chat_id or not source.user_id
or not self._telegram_topic_mode_enabled(source)
):
return None
inbound = str(source.thread_id or "")
if inbound and inbound not in self._TELEGRAM_GENERAL_TOPIC_IDS:
return None
session_db = self._sync_session_db()
if session_db is None:
return None
try:
bindings = session_db.list_telegram_topic_bindings_for_chat(
chat_id=str(source.chat_id), profile_name=self._telegram_topic_profile_name(source)
)
except Exception:
logger.debug("topic-recover: read failed", exc_info=True)
return None
for b in bindings or (): # newest-first
if str(b.get("user_id") or "") == str(source.user_id):
recovered = str(b.get("thread_id") or "")
return recovered if recovered and recovered != inbound else None
return None
# ── Telegram topic mode: /topic activation helpers ──────────────────────────────────────
async def _get_telegram_topic_capabilities(self, source: SessionSource) -> dict:
"""Read Telegram private-topic capability flags via Bot API getMe."""
bot = getattr(self._delivery_adapter_for(source), "_bot", None)
if bot is None or not hasattr(bot, "get_me"):
return {"checked": False}
try:
me = await bot.get_me()
except Exception:
logger.debug("Failed to fetch Telegram getMe topic capabilities", exc_info=True)
return {"checked": False}
def _field(name: str):
if hasattr(me, name):
return getattr(me, name)
api_kwargs = getattr(me, "api_kwargs", None)
if isinstance(api_kwargs, dict) and name in api_kwargs:
return api_kwargs[name]
return me.get(name) if isinstance(me, dict) else None
return {"checked": True, **{k: _field(k) for k in ("has_topics_enabled", "allows_users_to_create_topics")}}
async def _ensure_telegram_system_topic(self, source: SessionSource) -> None:
"""Create/pin the managed System topic after /topic activation when possible."""
adapter = self._delivery_adapter_for(source)
create_topic = getattr(adapter, "_create_dm_topic", None) if adapter is not None and source.chat_id else None
if not callable(create_topic):
return
try:
thread_id = await create_topic(int(source.chat_id), t("gateway.topic.system_topic_name"))
except Exception:
logger.debug("Failed to create Telegram System topic", exc_info=True)
return
if not thread_id:
return
try:
send_result = await adapter.send(
source.chat_id, t("gateway.topic.system_topic_intro"), metadata={"thread_id": str(thread_id)},
)
message_id = getattr(send_result, "message_id", None)
except Exception:
logger.debug("Failed to send Telegram System topic intro", exc_info=True)
return
bot = getattr(adapter, "_bot", None)
if not message_id or bot is None or not hasattr(bot, "pin_chat_message"):
return
try:
await bot.pin_chat_message(chat_id=int(source.chat_id), message_id=int(message_id), disable_notification=True)
except Exception:
logger.debug("Failed to pin Telegram System topic intro", exc_info=True)
async def _send_telegram_topic_setup_image(self, source: SessionSource) -> None:
"""Send the bundled BotFather Threads Settings screenshot when available."""
adapter = self._delivery_adapter_for(source)
image_path = Path(__file__).resolve().parent / "assets" / "telegram-botfather-threads-settings.jpg"
if adapter is None or not source.chat_id or not hasattr(adapter, "send_image_file") or not image_path.exists():
return
try:
await adapter.send_image_file(
chat_id=source.chat_id, image_path=str(image_path), caption=t("gateway.topic.setup_image_caption"),
metadata={"thread_id": str(source.thread_id)} if source.thread_id else None,
)
except Exception:
logger.debug("Failed to send Telegram topic setup image", exc_info=True)
# ── title sanitizers ────────────────────────────────────────────────────────────────────
def _sanitize_telegram_topic_title(self, title: str) -> str:
"""Bot API-safe forum topic name: names are 1-128 chars; keep room for multi-byte titles."""
cleaned = _collapse_title(title)
return cleaned if len(cleaned) <= 120 else cleaned[:117].rstrip() + "..."
def _sanitize_discord_thread_title(self, title: str) -> str:
"""Discord-safe thread title: the 100-char cap is measured in UTF-16 code units (emoji count
double), so truncate with the UTF-16 helpers rather than Python code-point slices."""
cleaned = _collapse_title(title)
return cleaned if utf16_len(cleaned) <= 80 else _prefix_within_utf16_limit(cleaned, 77).rstrip() + "..."
# ── Discord auto-thread lanes ───────────────────────────────────────────────────────────
def _is_discord_auto_thread_lane(self, source: SessionSource) -> bool:
"""Return True only for Discord threads Hermes just auto-created."""
return (
source.platform == Platform.DISCORD and source.chat_type == "thread"
and bool(getattr(source, "auto_thread_created", False)) and bool(source.thread_id)
and bool(getattr(source, "auto_thread_initial_name", None))
)
def _is_relay_discord_channel_lane(self, source: SessionSource) -> bool:
"""Shape-only check: a relay-delivered Discord CHANNEL event whose reply the connector MAY
auto-thread (title-turn registration gate). Deliberately does NOT consult the send-result
cache — before delivery the feedback can't exist; the rename lane polls it at fire time."""
return (
source.platform == Platform.DISCORD and bool(source.chat_id) and not source.thread_id
and source.chat_type in ("group", "channel")
and getattr(source, "delivered_via_upstream_relay", False) is True
)
def _relay_auto_thread_info(self, source: SessionSource) -> Optional[Tuple[str, str]]:
"""(thread_id, initial_name) when the RELAY connector auto-threaded our reply — the title-turn
sibling of _is_discord_auto_thread_lane (whose markers only exist from turn 2 on; the title
turn's source is the PARENT channel event).
Preferred: the connector's per-message ``prospective_thread_id`` stamp (anchor message id ==
the thread it will create), exact even when several auto-threads spawn from one channel;
the connector's created-name guard enforces no-clobber. Fallback: the per-chat send-result
cache (older connectors), which only ever renamed the FIRST thread.
"""
from gateway.run import _as_thread_info
if (
source.platform != Platform.DISCORD or not source.chat_id
or not getattr(source, "delivered_via_upstream_relay", False)
):
return None
prospective = getattr(source, "prospective_thread_id", None)
if prospective:
# Deterministic per-thread identity; the empty initial-name marker signals the caller
# to rely on the connector-side no-clobber guard.
return (str(prospective), "")
info_fn = getattr(self._delivery_adapter_for(source), "auto_thread_info_for_chat", None)
if not callable(info_fn):
return None
with suppress(Exception):
return _as_thread_info(info_fn(str(source.chat_id)))
return None
async def _await_relay_auto_thread_info(self, source: SessionSource) -> Optional[Tuple[str, str]]:
"""``_relay_auto_thread_info``, waited out until this turn delivers (the legacy send-result
path can only answer once the reply is sent; the caller asks at title time, one turn early).
The timeout is only a backstop for a turn that never sends: the turn's own inactivity limit."""
from gateway.run import _as_thread_info, _float_env
# The connector-stamped prospective id is known at ingest, so most sessions answer here.
known = self._relay_auto_thread_info(source)
if known is not None:
return known
wait_fn = getattr(self._delivery_adapter_for(source), "wait_for_auto_thread_info", None)
if not callable(wait_fn) or not source.chat_id:
return None
# 0 means the operator disabled the turn limit; the backstop still needs one.
timeout = _float_env("HERMES_AGENT_TIMEOUT", 1800) or 1800
with suppress(Exception):
return _as_thread_info(await wait_fn(str(source.chat_id), timeout))
return None
async def _rename_discord_auto_thread_for_session_title(
self, source: SessionSource, session_id: str, title: str,
relay_info: Optional[Tuple[str, str]] = None,
) -> None:
"""Best-effort semantic rename of a newly auto-created Discord thread. ``relay_info`` is the
connector's (thread_id, initial_name) feedback, supplied on the title turn where the source
is the parent-channel event without auto-thread markers (see _relay_auto_thread_info)."""
if relay_info is None and not await asyncio.to_thread(self._is_discord_auto_thread_lane, source):
# Relay title turn with no feedback captured at schedule time: the title comes off the
# user's opening message, so it beats the delivery that produces the connector's
# send-result feedback by the whole length of the turn. None here = a true miss.
if not self._is_relay_discord_channel_lane(source):
return
relay_info = await self._await_relay_auto_thread_info(source)
if relay_info is None:
return
adapter = self._delivery_adapter_for(source) if getattr(self, "adapters", None) else None
rename_thread = getattr(adapter, "rename_thread", None)
if rename_thread is None:
return
relay = relay_info is not None
target_thread_id = relay_info[0] if relay else str(source.thread_id)
thread_name = self._sanitize_discord_thread_title(title)
# Relay: ask the CONNECTOR to enforce the no-clobber guard from its own created-name memory —
# the gateway can't reproduce the initial name byte-for-byte (normalization drift silently
# declined every rename). Its egress guard resolves the tenant from caches keyed by the PARENT
# channel chat_id, so pass it or the lookup misses. Native: the source IS the thread; guard on
# the initial name.
rename_kwargs = (
{"prefer_connector_created": True, "parent_chat_id": str(source.chat_id) if source.chat_id else None}
if relay else {"only_if_current_name": getattr(source, "auto_thread_initial_name", None)}
)
logger.info(
"discord auto-thread rename: thread=%s lane=%s new_title=%r",
target_thread_id, "relay" if relay else "native", thread_name,
)
try:
renamed = await rename_thread(target_thread_id, thread_name, **rename_kwargs)
logger.info("discord auto-thread rename result: thread=%s applied=%s", target_thread_id, bool(renamed))
except TypeError:
logger.warning(
"Discord semantic thread rename raised TypeError (adapter=%s)", type(adapter).__name__, exc_info=True,
)
except Exception:
logger.debug("Failed to rename Discord auto-thread for generated session title", exc_info=True)
# ── title-thread → loop rename scheduling ───────────────────────────────────────────────
def _schedule_rename_from_title_thread(self, source: SessionSource, make_coro, label: str) -> None:
"""Schedule a best-effort rename coroutine onto the gateway loop from the auto-title thread.
The source is copied so the thread never shares the live dataclass with the loop; failures
are logged at debug and never propagate."""
from gateway.run import safe_schedule_threadsafe
try:
loop = asyncio.get_running_loop()
except RuntimeError:
loop = getattr(self, "_gateway_loop", None)
if loop is None or loop.is_closed():
return
copied_source = source
with suppress(Exception):
# Keep the live transport owner and identity; multiplex routes may run under a
# profile that does not own the Discord adapter/token.
from gateway.session_identity import replace_source
copied_source = replace_source(source)
future = safe_schedule_threadsafe(
make_coro(copied_source), loop, logger=logger, log_message=f"{label} failed to schedule",
)
def _log_rename_failure(fut) -> None:
try:
fut.result()
except Exception:
logger.debug("%s failed", label, exc_info=True)
if future is not None:
future.add_done_callback(_log_rename_failure)
def _schedule_discord_semantic_thread_rename(self, source: SessionSource, session_id: str, title: str) -> None:
"""Schedule Discord auto-thread rename from the auto-title background thread."""
if not title:
return
relay_info = None
if not self._is_discord_auto_thread_lane(source):
# Relay title turn: the source is the PARENT channel event (thread didn't exist at
# ingest). The auto-title races the delivery that fills the send-result cache, so a
# miss HERE is not a verdict: schedule whenever the SHAPE matches; the async rename
# lane polls the cache (bounded wait) and no-ops on a true miss.
relay_info = self._relay_auto_thread_info(source)
if relay_info is None and not self._is_relay_discord_channel_lane(source):
return
self._schedule_rename_from_title_thread(
source,
lambda copied: self._rename_discord_auto_thread_for_session_title(
copied, session_id, title, relay_info=relay_info
),
"Discord semantic thread rename",
)
def _schedule_telegram_topic_title_rename(self, source: SessionSource, session_id: str, title: str) -> None:
"""Schedule a topic rename from the auto-title background thread."""
if not title or not self._is_telegram_topic_lane(source) or self._telegram_topic_auto_rename_disabled(source):
return
self._schedule_rename_from_title_thread(
source,
lambda copied: self._rename_telegram_topic_for_session_title(copied, session_id, title),
"Telegram topic title rename",
)
def _telegram_topic_auto_rename_disabled(self, source: SessionSource) -> bool:
"""``gateway.platforms.telegram.extra.disable_topic_auto_rename``; default False (auto-rename on)."""
config = getattr(self, "config", None)
platform_cfg = config.platforms.get(source.platform) if config and getattr(config, "platforms", None) else None
if platform_cfg is None:
return False
return is_truthy_value((getattr(platform_cfg, "extra", None) or {}).get("disable_topic_auto_rename"))
async def _rename_telegram_topic_for_session_title(self, source: SessionSource, session_id: str, title: str) -> None:
"""Best-effort rename of a Telegram DM topic when Hermes auto-titles a session."""
if not await asyncio.to_thread(self._is_telegram_topic_lane, source) or not source.chat_id or not source.thread_id:
return
# Operator kill-switch, e.g. user-managed topics (ad-hoc Threaded Mode) that auto-rename
# would keep overwriting.
if self._telegram_topic_auto_rename_disabled(source):
return
# Skip operator-declared topics (extra.dm_topics): fixed names chosen by the operator;
# auto-renaming would silently mutate operator config. Check the class, not the instance —
# getattr() on a MagicMock auto-creates attributes, so every test double would match. Only
# dict-shaped returns count; a bare MagicMock or other sentinel shouldn't.
adapter = self._delivery_adapter_for(source)
get_info = getattr(type(adapter), "_get_dm_topic_info", None) if adapter is not None else None
if callable(get_info):
try:
operator_topic = get_info(adapter, str(source.chat_id), str(source.thread_id))
except Exception:
operator_topic = None
if isinstance(operator_topic, dict):
return
session_db = getattr(self, "_session_db", None)
if session_db is not None:
try:
binding = await session_db.get_telegram_topic_binding(
chat_id=str(source.chat_id), thread_id=str(source.thread_id),
profile_name=self._telegram_topic_profile_name(source),
)
if binding and str(binding.get("session_id") or "") != str(session_id):
return
except Exception:
logger.debug("Failed to verify Telegram topic binding before rename", exc_info=True)
return
if adapter is None:
return
topic_name = self._sanitize_telegram_topic_title(title)
try:
rename_topic = getattr(adapter, "rename_dm_topic", None)
if rename_topic is not None:
await rename_topic(chat_id=str(source.chat_id), thread_id=str(source.thread_id), name=topic_name)
return
bot = getattr(adapter, "_bot", None)
edit_forum_topic = getattr(bot, "edit_forum_topic", None) or getattr(bot, "editForumTopic", None)
if edit_forum_topic is None:
return
try:
await edit_forum_topic(chat_id=int(source.chat_id), message_thread_id=int(source.thread_id), name=topic_name)
except (TypeError, ValueError):
await edit_forum_topic(chat_id=source.chat_id, message_thread_id=source.thread_id, name=topic_name)
except Exception:
logger.debug("Failed to rename Telegram topic for auto-generated title", exc_info=True)
# ── /topic command bodies ───────────────────────────────────────────────────────────────
async def _disable_telegram_topic_mode_for_chat(self, source: SessionSource) -> str:
"""Cleanly disable topic mode for a chat via /topic off."""
if not self._session_db:
from hermes_state import format_session_db_unavailable
return format_session_db_unavailable(prefix=t("gateway.shared.session_db_unavailable_prefix"))
chat_id = str(source.chat_id or "")
if not chat_id:
return t("gateway.topic.no_chat_id")
profile_name = self._telegram_topic_profile_name(source)
currently_enabled = False
with suppress(Exception):
currently_enabled = await self._session_db.is_telegram_topic_mode_enabled(
chat_id=chat_id, user_id=str(source.user_id or ""), profile_name=profile_name,
)
if not currently_enabled:
return t("gateway.topic.mode_not_enabled")
try:
await self._session_db.disable_telegram_topic_mode(chat_id=chat_id, profile_name=profile_name)
except Exception as exc:
logger.exception("Failed to disable Telegram topic mode")
return t("gateway.topic.disable_failed", error=exc)
# Reset per-profile+chat debounce state so the next activation doesn't see a stale cooldown.
# See #76423.
cooldown_key = self._telegram_topic_cooldown_key(source)
for attr in ("_telegram_lobby_reminder_ts", "_telegram_capability_hint_ts") if cooldown_key else ():
store = getattr(self, attr, None)
if isinstance(store, dict):
store.pop(cooldown_key, None)
return t("gateway.topic.mode_disabled")
async def _telegram_topic_root_status_message(self, source: SessionSource) -> str:
lines = [t("gateway.topic.status_enabled"), "", t("gateway.topic.status_how_to"), ""]
try:
sessions = await self._session_db.list_unlinked_telegram_sessions_for_user(
chat_id=str(source.chat_id), user_id=str(source.user_id),
profile_name=self._telegram_topic_profile_name(source), limit=10,
)
except Exception:
logger.debug("Failed to list unlinked Telegram sessions", exc_info=True)
sessions = []
if sessions:
lines.append(t("gateway.topic.previous_unlinked"))
for session in sessions:
preview = str(session.get("preview") or "").strip()
lines.append(
f"- {session.get('title') or t('gateway.topic.untitled_session')} — `{session.get('id') or ''}`"
+ (f" — {preview}" if preview else "")
)
lines.extend(["", t("gateway.topic.restore_one"), *_topic_restore_steps(),
t("gateway.topic.restore_example", session_id=sessions[0].get("id"))])
else:
lines.extend([t("gateway.topic.no_unlinked"), "", t("gateway.topic.restore_later"), *_topic_restore_steps()])
return "\n".join(lines)
async def _restore_telegram_topic_session(self, event: MessageEvent, raw_session_id: str) -> str:
"""Restore an existing Telegram-owned Hermes session into this topic."""
source = event.source
db = self._session_db
session_id = await db.resolve_session_id(raw_session_id.strip())
session = await db.get_session(session_id) if session_id else None
if not session:
return t("gateway.topic.session_not_found", session_id=raw_session_id.strip())
if str(session.get("source") or "") != "telegram":
return t("gateway.topic.not_telegram_session")
if str(session.get("user_id") or "") != str(source.user_id):
return t("gateway.topic.not_your_session")
linked = await db.is_telegram_session_linked_to_topic(session_id=session_id)
topic_profile = self._telegram_topic_profile_name(source)
current_binding = await db.get_telegram_topic_binding(
chat_id=str(source.chat_id), thread_id=str(source.thread_id), profile_name=topic_profile,
)
already_linked = t("gateway.topic.already_linked")
if linked and (not current_binding or current_binding.get("session_id") != session_id):
return already_linked
try:
await db.bind_telegram_topic(
chat_id=str(source.chat_id), thread_id=str(source.thread_id), user_id=str(source.user_id),
session_key=self._session_key_for_source(source), session_id=session_id, managed_mode="restored",
profile_name=topic_profile,
)
except ValueError as exc:
if "already linked" in str(exc):
return already_linked
raise
title = await db.get_session_title(session_id) or session_id
last_assistant = None
with suppress(Exception):
for message in reversed(await db.get_messages(session_id)):
if message.get("role") != "assistant":
continue
projected = project_compaction_message_for_display(message)
if projected is not None and projected.get("content"):
last_assistant = str(projected.get("content"))
break
response = t("gateway.topic.restored", title=title)
return response + (t("gateway.topic.restored_last_message", text=last_assistant) if last_assistant else "")