fix(slack,telegram): align unfurl merge with TS spread + small parity fixes

Address review findings on the chat@4.27.0 adapter bug-fix sweep:

1. Slack ``_merge_unfurl_into_preview``: TS does
   ``{ ...preview, ...unfurl }`` which lets unfurl OVERRIDE the
   preview's existing fields (except ``title``, which is short-
   circuited at the ``_enrich_links`` call site when the preview
   already has one). The previous Python implementation preserved
   non-None preview fields, so a preview that picked up a description
   from one source could never be overwritten by a more authoritative
   unfurl. Switch to "unfurl wins when present" semantics for
   ``description`` / ``image_url`` / ``site_name``; ``title`` matches
   TS via the existing ``_enrich_links`` short-circuit. Add a
   regression test (``preview.description = "old"``,
   ``unfurl.description = "new"`` -> output is ``"new"``).

2. Slack ``_TRAILING_SLASH_PATTERN.sub("", url)``: TS
   ``url.replace(TRAILING_SLASH_PATTERN, "")`` strips a single
   trailing ``/``; Python's ``re.sub`` defaults to all matches. Pin
   ``count=1`` for parity (also locks down behaviour if the regex
   ever loosens beyond an end-anchored match).

3. Slack: regression test that two ``message_changed`` events for the
   same message ts overwrite the cached unfurl (rather than merging
   in stale entries). Locks in the ``state.set(...)`` overwrite
   semantics that the 1h cache TTL relies on.

4. Slack ``_extract_links``: regression test that a URL containing
   an unbalanced ``(`` survives the angle-bracket regex (a tightening
   of the URL pattern would silently drop wikipedia-style links).

5. Slack ``_enrich_links`` call site: comment noting that each
   message containing a not-yet-unfurled link adds up to ~2s of
   latency worst-case (``_UNFURL_WAIT_MS``).

6. Telegram MarkdownV2 renderer fallback: comment explaining the
   trade-off vs upstream's ``node satisfies never`` exhaustive check
   (Python silently degrades unknown nodes to escaped text rather
   than raising, prioritising delivery over compile-time signal).

7. Slack ``test_slack_format.py``: add a missing test for the bare-
   mention regex with an email tail (``@user@example.com`` ->
   ``<@user>@example.com``) — pins the boundary case between a real
   mention and an email-style suffix glued to it.

https://claude.ai/code/session_01FyMxQn2BEAzmwKS1GZczKj

Author: claude

src/chat_sdk/adapters/slack/adapter.py

@@ -1775,7 +1775,15 @@ def _extract_links(self, event: dict[str, Any]) -> list[LinkPreview]:
         previews: list[LinkPreview] = []
         for url in urls:
             preview = self._create_link_preview(url)
-            unfurl = unfurls.get(url) or unfurls.get(_TRAILING_SLASH_PATTERN.sub("", url)) or unfurls.get(f"{url}/")
+            # TS uses ``url.replace(TRAILING_SLASH_PATTERN, "")`` (no ``g``
+            # flag) which strips a single trailing ``/``. Python's
+            # ``re.sub`` defaults to replacing all occurrences, so we
+            # pin ``count=1`` for parity. (Practically the regex anchors
+            # at end-of-string so only one match exists, but locking
+            # this in prevents drift if the pattern ever loosens.)
+            unfurl = (
+                unfurls.get(url) or unfurls.get(_TRAILING_SLASH_PATTERN.sub("", url, count=1)) or unfurls.get(f"{url}/")
+            )
             if unfurl:
                 preview = self._merge_unfurl_into_preview(preview, unfurl)
             previews.append(preview)
@@ -1785,16 +1793,21 @@ def _extract_links(self, event: dict[str, Any]) -> list[LinkPreview]:
     def _merge_unfurl_into_preview(preview: LinkPreview, unfurl: dict[str, str | None]) -> LinkPreview:
         """Return a new LinkPreview with unfurl metadata merged in.
 
-        Only fills fields that are missing on the preview — user-supplied
-        metadata (e.g. ``title`` from a Slack message URL) wins over the
-        attachment-derived unfurl. ``fetch_message`` is preserved.
+        Mirrors the TS spread ``{ ...preview, ...unfurl }``: the unfurl
+        values OVERRIDE the preview's ``description`` / ``image_url`` /
+        ``site_name`` (the unfurled attachment is the authoritative
+        source). ``title`` is short-circuited by callers (``_enrich_links``
+        skips merging when the preview already has a title), but for the
+        same-event ``_extract_links`` path the unfurl's title also wins
+        when present. ``fetch_message`` is never present on the unfurl
+        and is preserved from the preview.
         """
         return LinkPreview(
             url=preview.url,
-            title=preview.title if preview.title is not None else unfurl.get("title"),
-            description=preview.description if preview.description is not None else unfurl.get("description"),
-            image_url=preview.image_url if preview.image_url is not None else unfurl.get("image_url"),
-            site_name=preview.site_name if preview.site_name is not None else unfurl.get("site_name"),
+            title=unfurl.get("title") if unfurl.get("title") is not None else preview.title,
+            description=unfurl.get("description") if unfurl.get("description") is not None else preview.description,
+            image_url=unfurl.get("image_url") if unfurl.get("image_url") is not None else preview.image_url,
+            site_name=unfurl.get("site_name") if unfurl.get("site_name") is not None else preview.site_name,
             fetch_message=preview.fetch_message,
         )
 
@@ -1906,7 +1919,7 @@ async def _enrich_links(self, links: list[LinkPreview], message_ts: str | None)
                 continue
             unfurl = (
                 stored.get(link.url)
-                or stored.get(_TRAILING_SLASH_PATTERN.sub("", link.url))
+                or stored.get(_TRAILING_SLASH_PATTERN.sub("", link.url, count=1))
                 or stored.get(f"{link.url}/")
             )
             if unfurl:
@@ -2019,6 +2032,12 @@ async def _parse_slack_message(
                 self._create_attachment(f, team_id=event.get("team") or event.get("team_id"))
                 for f in event.get("files", [])
             ],
+            # ``_enrich_links`` polls the unfurl cache for up to
+            # ``_UNFURL_WAIT_MS`` (2000 ms) before giving up, so every
+            # message containing a not-yet-unfurled link adds up to
+            # ~2s of latency to message handling worst-case (it returns
+            # immediately when the cache is already populated or when
+            # there are no links to enrich).
             links=await self._enrich_links(self._extract_links(event), event.get("ts")),
         )
 

src/chat_sdk/adapters/telegram/format_converter.py

@@ -155,6 +155,16 @@ def _render_markdown_v2(node: Content) -> str:
 
     # Fallback for unknown node types: render children if available, else
     # escape any value, else empty.
+    #
+    # Trade-off vs. upstream: TS uses ``node satisfies never`` to make
+    # adding a new mdast node a *compile-time* failure here. In Python
+    # we don't have that guarantee, so an unknown node is silently
+    # converted to its escaped value or empty string rather than
+    # raised. We accept this so that future mdast extensions don't
+    # break message delivery (a stray unknown node should degrade to
+    # plain text, not a crash) — at the cost of losing the upstream
+    # signal that a renderer arm is missing. Test coverage of the
+    # renderer should grow alongside any new node kinds we recognise.
     if children:
         return _render_children(children)
     value = node.get("value")

tests/test_slack_webhook.py

@@ -1222,3 +1222,127 @@ async def test_enrich_links_returns_unchanged_with_no_chat(self):
         original = [_LinkPreview(url="https://example.com")]
         enriched = await adapter._enrich_links(original, "ts1")
         assert enriched is original
+
+    @pytest.mark.asyncio
+    async def test_enrich_links_unfurl_overrides_existing_description(self):
+        """Unfurl description WINS over a pre-existing preview description.
+
+        TS does ``{ ...link, ...unfurl }`` (spread) which overwrites the
+        preview's description. The previous Python implementation
+        preserved the preview's description when non-None — silently
+        diverging from upstream.
+
+        What to fix if this fails: ``_merge_unfurl_into_preview`` in
+        ``src/chat_sdk/adapters/slack/adapter.py`` must let the unfurl
+        values win over the preview's description / image_url /
+        site_name (only ``title`` is short-circuited at the
+        ``_enrich_links`` level).
+        """
+        from chat_sdk.types import LinkPreview as _LinkPreview
+
+        adapter = _make_adapter()
+        state = _make_mock_state()
+        chat = _make_mock_chat(state)
+        await adapter.initialize(chat)
+
+        state._cache["slack:unfurls:t-override"] = {
+            "https://example.com": {
+                "title": None,  # title not present → no short-circuit clobber
+                "description": "new",
+                "image_url": "https://example.com/new.png",
+                "site_name": "Example",
+            }
+        }
+        # Preview already has an "old" description — unfurl must win.
+        original = [
+            _LinkPreview(
+                url="https://example.com",
+                description="old",
+                image_url="https://example.com/old.png",
+                site_name="OldSite",
+            )
+        ]
+        enriched = await adapter._enrich_links(original, "t-override")
+        assert enriched[0].description == "new"
+        assert enriched[0].image_url == "https://example.com/new.png"
+        assert enriched[0].site_name == "Example"
+
+    @pytest.mark.asyncio
+    async def test_message_changed_overwrites_cached_unfurl_not_merge(self):
+        """Two ``message_changed`` events for the same ts overwrite the cache.
+
+        Slack delivers multi-edit unfurls as separate ``message_changed``
+        events. Each event carries the FULL, current attachment list — a
+        merge would keep stale entries from the previous edit. The cache
+        ``set()`` semantics must overwrite, not merge.
+
+        What to fix if this fails: ``_handle_message_changed`` in
+        ``src/chat_sdk/adapters/slack/adapter.py`` must call
+        ``state.set(...)`` (which overwrites) and never read-merge-write.
+        """
+        adapter = _make_adapter(bot_user_id="U_BOT")
+        state = _make_mock_state()
+        chat = _make_mock_chat(state)
+        await adapter.initialize(chat)
+
+        def _make_changed_body(url: str, title: str) -> str:
+            return json.dumps(
+                {
+                    "type": "event_callback",
+                    "team_id": "T123",
+                    "event": {
+                        "type": "message",
+                        "subtype": "message_changed",
+                        "channel": "C_CHAN",
+                        "ts": "1234567890.222222",
+                        "message": {
+                            "ts": "1234567890.111111",
+                            "attachments": [
+                                {
+                                    "from_url": url,
+                                    "title": title,
+                                    "text": f"body for {title}",
+                                },
+                            ],
+                        },
+                    },
+                }
+            )
+
+        # First edit caches a single unfurl for URL_A.
+        await adapter.handle_webhook(_make_signed_request(_make_changed_body("https://a.example.com", "First")))
+        await asyncio.sleep(0)
+        first = state._cache.get("slack:unfurls:1234567890.111111")
+        assert first is not None
+        assert "https://a.example.com" in first
+
+        # Second edit caches an unfurl for a DIFFERENT URL (URL_B).
+        # If the implementation merged, URL_A would still be in the cache.
+        await adapter.handle_webhook(_make_signed_request(_make_changed_body("https://b.example.com", "Second")))
+        await asyncio.sleep(0)
+        second = state._cache.get("slack:unfurls:1234567890.111111")
+        assert second is not None
+        assert "https://b.example.com" in second
+        assert "https://a.example.com" not in second, "second message_changed must overwrite, not merge"
+        assert second["https://b.example.com"]["title"] == "Second"
+
+    def test_extract_links_url_with_open_paren_survives_parser(self):
+        """A URL containing ``(`` (unbalanced open paren) is preserved.
+
+        Slack delivers URLs in angle brackets — ``<URL>`` — which the
+        adapter parses with ``re.finditer(r"<(https?://[^>]+)>", ...)``.
+        The character class ``[^>]+`` accepts ``(`` so a URL such as
+        ``https://en.wikipedia.org/wiki/Pi_(letter)`` makes it through
+        intact. The other URL extraction path (rich_text blocks) gets
+        the URL as a struct field, so parens are also fine there.
+
+        What to fix if this fails: the URL pattern in ``_extract_links``
+        in ``src/chat_sdk/adapters/slack/adapter.py`` was tightened in a
+        way that drops parentheses.
+        """
+        adapter = _make_adapter()
+        url_with_paren = "https://en.wikipedia.org/wiki/Pi_(letter"  # unbalanced `(` no closing `)`
+        event = {"text": f"see <{url_with_paren}>"}
+        links = adapter._extract_links(event)
+        assert len(links) == 1
+        assert links[0].url == url_with_paren