From 31e59fe44d18498ae53f624a3d3d5dbbad2d165e Mon Sep 17 00:00:00 2001
From: Tranquil-Flow <66773372+Tranquil-Flow@users.noreply.github.com>
Date: Sun, 21 Jun 2026 07:28:38 -0700
Subject: [PATCH] fix(telegram): preserve newlines in rich slash-command output
 (#46070)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bot API 10.1 sendRichMessage treats a lone newline as a soft break, so
multi-line content joined with "\n".join(lines) — slash-command lists,
etc. — collapses into a single paragraph. Normalize single newlines to
Markdown hard breaks (two trailing spaces) in _rich_message_payload,
leaving paragraph breaks and fenced code blocks untouched.

Fixes #46070
---
 plugins/platforms/telegram/adapter.py        |  38 +++++-
 tests/gateway/test_telegram_rich_newlines.py | 118 +++++++++++++++++++
 2 files changed, 155 insertions(+), 1 deletion(-)
 create mode 100644 tests/gateway/test_telegram_rich_newlines.py

diff --git a/plugins/platforms/telegram/adapter.py b/plugins/platforms/telegram/adapter.py
index fbc98c6edec..73431cd26bd 100644
--- a/plugins/platforms/telegram/adapter.py
+++ b/plugins/platforms/telegram/adapter.py
@@ -352,6 +352,38 @@ def _wrap_markdown_tables(text: str) -> str:
     return '\n'.join(out)
 
 
+# ---------------------------------------------------------------------------
+# Rich-message newline normalization
+# ---------------------------------------------------------------------------
+
+# Matches fenced code blocks (```...\n...\n```), used to protect their
+# content from newline normalization.
+_RICH_CODE_FENCE_RE = re.compile(r'(```[^\n]*\n[\s\S]*?```)', re.MULTILINE)
+
+
+def _rich_normalize_linebreaks(text: str) -> str:
+    """Convert single ``\\n`` to Markdown hard breaks for the rich-message path.
+
+    Standard Markdown treats a lone ``\\n`` as whitespace (soft break), so
+    Bot API 10.1 ``sendRichMessage`` collapses multi-line content — e.g.
+    slash-command lists joined with ``"\\n".join(lines)`` — into a single
+    paragraph.  Adding two trailing spaces before each single newline
+    forces a hard line break (``<br>``) in the rendered output.
+
+    Paragraph breaks (``\\n\\n``) and fenced code blocks are left untouched.
+    """
+    if not text or '\n' not in text:
+        return text
+
+    parts = _RICH_CODE_FENCE_RE.split(text)
+    for i, part in enumerate(parts):
+        # Even indices are outside code fences; odd indices are fence content.
+        if i % 2 == 0:
+            # Convert single \n (not adjacent to another \n) to "  \n".
+            parts[i] = re.sub(r'(?<!\n)\n(?!\n)', '  \n', part)
+    return ''.join(parts)
+
+
 class TelegramAdapter(BasePlatformAdapter):
     """
     Telegram bot adapter.
@@ -1107,8 +1139,12 @@ class TelegramAdapter(BasePlatformAdapter):
 
         Never pass ``format_message(content)`` here — that converts to
         MarkdownV2 and would escape/destroy rich syntax like table pipes.
+
+        Single newlines are normalized to Markdown hard breaks so that
+        multi-line content (slash-command lists, etc.) renders correctly
+        in the rich-message path.  See ``_rich_normalize_linebreaks``.
         """
-        payload: Dict[str, Any] = {"markdown": content}
+        payload: Dict[str, Any] = {"markdown": _rich_normalize_linebreaks(content)}
         if skip_entity_detection:
             payload["skip_entity_detection"] = True
         return payload
diff --git a/tests/gateway/test_telegram_rich_newlines.py b/tests/gateway/test_telegram_rich_newlines.py
new file mode 100644
index 00000000000..f4bfac35578
--- /dev/null
+++ b/tests/gateway/test_telegram_rich_newlines.py
@@ -0,0 +1,118 @@
+"""Tests for rich-message newline normalization (issue #46070).
+
+When Bot API 10.1 ``sendRichMessage`` is available, slash-command responses
+are sent through the rich path with RAW markdown.  Standard Markdown treats
+a lone ``\\n`` as a soft line break (renders as whitespace), so multi-line
+command output collapses into a single paragraph on Telegram.
+
+``_rich_message_payload`` must normalize single newlines to Markdown hard
+breaks (two trailing spaces + ``\\n``) so they render as visible line breaks.
+Paragraph breaks (``\\n\\n``) and fenced code blocks must be preserved.
+
+The ``telegram`` package is mocked by ``tests/gateway/conftest.py``, so these
+tests construct a real ``TelegramAdapter``.
+"""
+
+import pytest
+
+from plugins.platforms.telegram.adapter import TelegramAdapter
+
+
+@pytest.fixture()
+def adapter():
+    """Bare adapter instance — _rich_message_payload doesn't use self."""
+    return object.__new__(TelegramAdapter)
+
+
+class TestRichMessageNewlineNormalization:
+    """Verify _rich_message_payload normalizes single \\n to hard breaks."""
+
+    def test_single_newlines_become_hard_breaks(self, adapter):
+        """A lone \\n must gain two trailing spaces (Markdown hard break).
+
+        Standard Markdown soft-break rendering causes Bot API 10.1
+        ``sendRichMessage`` to collapse multi-line content into one paragraph.
+        """
+        content = "Line 1\nLine 2\nLine 3"
+        payload = adapter._rich_message_payload(content)
+        md = payload["markdown"]
+        # Each single \n should now be "  \n" (two spaces + newline)
+        assert "  \n" in md, f"Expected hard break '  \\n' in {md!r}"
+        assert "Line 1  \nLine 2  \nLine 3" == md
+
+    def test_paragraph_breaks_preserved(self, adapter):
+        """Double newlines (paragraph breaks) must NOT gain extra spaces."""
+        content = "Paragraph 1\n\nParagraph 2"
+        payload = adapter._rich_message_payload(content)
+        md = payload["markdown"]
+        # \n\n should remain as-is — no trailing spaces injected
+        assert "Paragraph 1\n\nParagraph 2" == md
+
+    def test_mixed_single_and_double_newlines(self, adapter):
+        """Content with both list items and paragraph breaks must be handled correctly."""
+        content = (
+            "Header\n\n"
+            "`/new` -- Start\n"
+            "`/model` -- Switch\n"
+            "`/reset` -- Reset\n\n"
+            "Footer"
+        )
+        payload = adapter._rich_message_payload(content)
+        md = payload["markdown"]
+        # Paragraph breaks preserved
+        assert "Header\n\n" in md
+        assert "\n\nFooter" in md
+        # Single newlines converted to hard breaks
+        assert "`/new` -- Start  \n`/model` -- Switch  \n`/reset` -- Reset" in md
+
+    def test_fenced_code_block_newlines_preserved(self, adapter):
+        """Newlines inside fenced code blocks must NOT gain trailing spaces."""
+        content = "Before\n```\ncode line 1\ncode line 2\n```\nAfter"
+        payload = adapter._rich_message_payload(content)
+        md = payload["markdown"]
+        # Code block content should be untouched
+        assert "```\ncode line 1\ncode line 2\n```" in md
+        # But the \n before ``` and after ``` should be hard breaks
+        assert "Before  \n```" in md
+        assert "```  \nAfter" in md
+
+    def test_realistic_command_output(self, adapter):
+        """Simulates /commands output: header + list items + nav line."""
+        lines = [
+            "📊 Commands (24 total, page 1/2)",
+            "",
+            "`/new` -- Start a new session",
+            "`/model` -- Switch model",
+            "`/stop` -- Stop the agent",
+            "",
+            "Use /commands 2 for next page | /commands 1 for prev",
+        ]
+        content = "\n".join(lines)
+        payload = adapter._rich_message_payload(content)
+        md = payload["markdown"]
+        # Header paragraph break preserved
+        assert "📊 Commands (24 total, page 1/2)\n\n" in md
+        # List items have hard breaks
+        assert "`/new` -- Start a new session  \n" in md
+        assert "`/model` -- Switch model  \n" in md
+        # Nav paragraph break preserved
+        assert "\n\nUse /commands 2" in md
+
+    def test_no_trailing_space_on_last_line(self, adapter):
+        """The final line should not get trailing spaces (no newline after it)."""
+        content = "Line 1\nLine 2"
+        payload = adapter._rich_message_payload(content)
+        md = payload["markdown"]
+        # No trailing spaces at end of string
+        assert md == "Line 1  \nLine 2"
+        assert not md.endswith("  ")
+
+    def test_empty_and_single_line_unchanged(self, adapter):
+        """Empty string and single-line content should pass through."""
+        assert adapter._rich_message_payload("")["markdown"] == ""
+        assert adapter._rich_message_payload("Single line")["markdown"] == "Single line"
+
+    def test_skip_entity_detection_flag_preserved(self, adapter):
+        """The skip_entity_detection flag must still work after normalization."""
+        payload = adapter._rich_message_payload("Line 1\nLine 2", skip_entity_detection=True)
+        assert payload.get("skip_entity_detection") is True