feat(attachments): port rehydrateAttachment adapter hook + Thread serialization

Upstream Adapter.rehydrateAttachment rebuilds the fetch_data download
closure after a JSON roundtrip through the state adapter — essential for
queue/debounce concurrency strategies, where entries pass through
JSON.stringify and lose any callable fields. This PR ports the hook to
Python: Adapter gains an optional rehydrate_attachment method (default
no-op on BaseAdapter), Attachment gains a serializable fetch_metadata
dict, and Chat._rehydrate_message now threads the active adapter and
invokes the hook on any attachment whose fetch_data was stripped.
Per-adapter implementations land on Slack (url + teamId), Teams (url),
Google Chat (resourceName + url), Telegram (fileId), and WhatsApp
(mediaId); Discord, GitHub and Linear intentionally do not implement it
(upstream parity — they use public URLs or have no file attachments).

Closes 3 [concurrency: queue attachment rehydration] fidelity gaps.
Refs #52.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: patrick-chinchill

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- **`Adapter.rehydrate_attachment` hook + `Attachment.fetch_metadata`** (#52):
+  port of the upstream `rehydrateAttachment` adapter hook that restores
+  `fetch_data` closures after JSON serialization. `Chat._rehydrate_message`
+  now accepts the active adapter and invokes the hook on every attachment
+  that lost its callback during a queue/debounce roundtrip. `Attachment`
+  gains a serializable `fetch_metadata: dict[str, str] | None` field that
+  persists adapter-specific identifiers (Slack `url` + `teamId`, Teams
+  `url`, Google Chat `resourceName` + `url`, Telegram `fileId`, WhatsApp
+  `mediaId`) through `to_json` / `from_json`. Implementations land on
+  Slack, Teams, Google Chat, Telegram, and WhatsApp; Discord / GitHub /
+  Linear do not (upstream parity — those platforms either use public URLs
+  or carry no file attachments). Closes the 3
+  `[concurrency: queue attachment rehydration]` fidelity gaps in
+  `chat.test.ts`.
+
 ## 0.4.26.1 (2026-04-23)
 
 Python-only follow-up on `0.4.26`. Still alpha — APIs may change.

src/chat_sdk/adapters/google_chat/adapter.py

@@ -2612,53 +2612,92 @@ def _create_attachment(self, att: dict[str, Any]) -> Attachment:
         elif content_type.startswith("audio/"):
             att_type = "audio"
 
-        # Build fetchData closure
+        fetch_meta: dict[str, str] = {}
+        if resource_name:
+            fetch_meta["resourceName"] = resource_name
+        if url:
+            fetch_meta["url"] = url
+
         fetch_data: Callable[[], Awaitable[bytes]] | None = None
         if resource_name or url:
-            adapter = self
-
-            async def _fetch_data() -> bytes:
-                # Prefer media.download API
-                if resource_name:
-                    token = await adapter._get_access_token()
-                    download_url = f"https://chat.googleapis.com/v1/media/{resource_name}?alt=media"
-                    session = await adapter._get_http_session()
-                    async with session.get(
-                        download_url,
-                        headers={"Authorization": f"Bearer {token}"},
-                    ) as response:
-                        if response.status >= 400:
-                            raise NetworkError(
-                                "gchat",
-                                f"Failed to download media: {response.status}",
-                            )
-                        return await response.read()
-
-                # Fallback to direct URL fetch (downloadUri)
-                if url:
-                    token = await adapter._get_access_token()
-                    session = await adapter._get_http_session()
-                    async with session.get(
-                        url,
-                        headers={"Authorization": f"Bearer {token}"},
-                    ) as response:
-                        if response.status >= 400:
-                            raise NetworkError(
-                                "gchat",
-                                f"Failed to fetch file: {response.status}",
-                            )
-                        return await response.read()
-
-                raise AuthenticationError("gchat", "Cannot fetch file: no URL or resource name")
-
-            fetch_data = _fetch_data
+            fetch_data = self._build_gchat_fetch_data(resource_name, url)
 
         return Attachment(
             type=att_type,  # type: ignore[arg-type]
             url=url,
             name=att.get("contentName"),
             mime_type=att.get("contentType"),
             fetch_data=fetch_data,
+            fetch_metadata=fetch_meta or None,
+        )
+
+    def _build_gchat_fetch_data(
+        self,
+        resource_name: str | None,
+        url: str | None,
+    ) -> Callable[[], Awaitable[bytes]]:
+        """Build a lazy ``fetch_data`` closure for a Google Chat attachment."""
+        adapter = self
+
+        async def _fetch_data() -> bytes:
+            # Prefer media.download API
+            if resource_name:
+                token = await adapter._get_access_token()
+                download_url = f"https://chat.googleapis.com/v1/media/{resource_name}?alt=media"
+                session = await adapter._get_http_session()
+                async with session.get(
+                    download_url,
+                    headers={"Authorization": f"Bearer {token}"},
+                ) as response:
+                    if response.status >= 400:
+                        raise NetworkError(
+                            "gchat",
+                            f"Failed to download media: {response.status}",
+                        )
+                    return await response.read()
+
+            # Fallback to direct URL fetch (downloadUri)
+            if url:
+                token = await adapter._get_access_token()
+                session = await adapter._get_http_session()
+                async with session.get(
+                    url,
+                    headers={"Authorization": f"Bearer {token}"},
+                ) as response:
+                    if response.status >= 400:
+                        raise NetworkError(
+                            "gchat",
+                            f"Failed to fetch file: {response.status}",
+                        )
+                    return await response.read()
+
+            raise AuthenticationError("gchat", "Cannot fetch file: no URL or resource name")
+
+        return _fetch_data
+
+    def rehydrate_attachment(self, attachment: Attachment) -> Attachment:
+        """Reconstruct ``fetch_data`` on a deserialized Google Chat attachment.
+
+        Pulls ``resourceName`` (preferred, used with media.download API) and
+        ``url`` (fallback) from ``fetch_metadata``.  Returns the attachment
+        unchanged when neither identifier is present.
+        """
+        meta = attachment.fetch_metadata or {}
+        resource_name = meta.get("resourceName")
+        url = meta.get("url") or attachment.url
+        if not (resource_name or url):
+            return attachment
+        return Attachment(
+            type=attachment.type,
+            url=attachment.url,
+            name=attachment.name,
+            mime_type=attachment.mime_type,
+            size=attachment.size,
+            width=attachment.width,
+            height=attachment.height,
+            data=attachment.data,
+            fetch_data=self._build_gchat_fetch_data(resource_name, url),
+            fetch_metadata=attachment.fetch_metadata,
         )
 
     # =========================================================================

src/chat_sdk/adapters/slack/adapter.py

@@ -1679,7 +1679,10 @@ async def _parse_slack_message(
                 edited=bool(event.get("edited")),
                 edited_at=edited_at,
             ),
-            attachments=[self._create_attachment(f) for f in event.get("files", [])],
+            attachments=[
+                self._create_attachment(f, team_id=event.get("team") or event.get("team_id"))
+                for f in event.get("files", [])
+            ],
             links=self._extract_links(event),
         )
 
@@ -1721,12 +1724,21 @@ def _parse_slack_message_sync(self, event: dict[str, Any], thread_id: str) -> Me
                 edited=bool(event.get("edited")),
                 edited_at=edited_at,
             ),
-            attachments=[self._create_attachment(f) for f in event.get("files", [])],
+            attachments=[
+                self._create_attachment(f, team_id=event.get("team") or event.get("team_id"))
+                for f in event.get("files", [])
+            ],
             links=self._extract_links(event),
         )
 
-    def _create_attachment(self, file: dict[str, Any]) -> Attachment:
-        """Create an Attachment from a Slack file object."""
+    def _create_attachment(self, file: dict[str, Any], team_id: str | None = None) -> Attachment:
+        """Create an Attachment from a Slack file object.
+
+        ``team_id`` identifies the workspace the file belongs to and is
+        stored in ``fetch_metadata`` so :meth:`rehydrate_attachment` can
+        rebuild the download closure (with workspace-specific token) after
+        the queue/debounce path JSON-serializes the message.
+        """
         url = file.get("url_private")
         # Capture token at creation time (during webhook processing)
         bot_token = self._get_token()
@@ -1741,18 +1753,13 @@ def _create_attachment(self, file: dict[str, Any]) -> Attachment:
             att_type = "audio"
 
         async def fetch_data() -> bytes:
-            import httpx
-
-            async with httpx.AsyncClient() as http:
-                resp = await http.get(url, headers={"Authorization": f"Bearer {bot_token}"})  # type: ignore[arg-type]
-                resp.raise_for_status()
-                content_type = resp.headers.get("content-type", "")
-                if "text/html" in content_type:
-                    raise RuntimeError(
-                        "Failed to download file from Slack: received HTML login page. "
-                        'Ensure your Slack app has the "files:read" OAuth scope.'
-                    )
-                return resp.content
+            return await self._fetch_slack_file(url, bot_token)  # type: ignore[arg-type]
+
+        fetch_meta: dict[str, str] = {}
+        if url:
+            fetch_meta["url"] = url
+        if team_id:
+            fetch_meta["teamId"] = team_id
 
         return Attachment(
             type=att_type,  # type: ignore[arg-type]
@@ -1763,6 +1770,71 @@ async def fetch_data() -> bytes:
             width=file.get("original_w"),
             height=file.get("original_h"),
             fetch_data=fetch_data if url else None,
+            fetch_metadata=fetch_meta or None,
+        )
+
+    async def _fetch_slack_file(self, url: str, token: str) -> bytes:
+        """Download a file from a Slack ``url_private`` endpoint.
+
+        Shared by :meth:`_create_attachment` (direct fetch closure) and
+        :meth:`rehydrate_attachment` (reconstructed closure after JSON
+        roundtrip).
+        """
+        import httpx
+
+        async with httpx.AsyncClient() as http:
+            resp = await http.get(url, headers={"Authorization": f"Bearer {token}"})
+            resp.raise_for_status()
+            content_type = resp.headers.get("content-type", "")
+            if "text/html" in content_type:
+                raise RuntimeError(
+                    "Failed to download file from Slack: received HTML login page. "
+                    'Ensure your Slack app has the "files:read" OAuth scope.'
+                )
+            return resp.content
+
+    def rehydrate_attachment(self, attachment: Attachment) -> Attachment:
+        """Reconstruct ``fetch_data`` on a deserialized Slack attachment.
+
+        Matches the upstream TS implementation: looks up the download URL
+        (and optional ``teamId`` for multi-workspace installations) from
+        ``attachment.fetch_metadata``, and rebuilds a ``fetch_data`` closure
+        that resolves the workspace-specific bot token at call time.
+
+        Returns the attachment unchanged when no URL is available.
+        """
+        meta = attachment.fetch_metadata or {}
+        url = meta.get("url") or attachment.url
+        team_id = meta.get("teamId")
+        if not url:
+            return attachment
+
+        adapter = self
+
+        async def fetch_data() -> bytes:
+            if team_id:
+                installation = await adapter.get_installation(team_id)
+                if installation is None:
+                    raise AuthenticationError(
+                        "slack",
+                        f"Installation not found for team {team_id}",
+                    )
+                token = installation.bot_token
+            else:
+                token = adapter._get_token()
+            return await adapter._fetch_slack_file(url, token)
+
+        return Attachment(
+            type=attachment.type,
+            url=attachment.url,
+            name=attachment.name,
+            mime_type=attachment.mime_type,
+            size=attachment.size,
+            width=attachment.width,
+            height=attachment.height,
+            data=attachment.data,
+            fetch_data=fetch_data,
+            fetch_metadata=attachment.fetch_metadata,
         )
 
     def _is_message_from_self(self, event: dict[str, Any]) -> bool:

src/chat_sdk/adapters/teams/adapter.py

@@ -14,6 +14,7 @@
 import json
 import os
 import re
+from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
 from typing import Any, Literal, NoReturn
 
@@ -580,11 +581,52 @@ def _create_attachment(self, att: dict[str, Any]) -> Attachment:
         elif content_type.startswith("audio/"):
             att_type = "audio"
 
+        url = att.get("contentUrl")
         return Attachment(
             type=att_type,
-            url=att.get("contentUrl"),
+            url=url,
             name=att.get("name"),
             mime_type=content_type or None,
+            fetch_metadata={"url": url} if url else None,
+            fetch_data=self._build_teams_fetch_data(url) if url else None,
+        )
+
+    def _build_teams_fetch_data(self, url: str) -> Callable[[], Awaitable[bytes]]:
+        """Build a lazy ``fetch_data`` closure for a Teams file URL."""
+
+        async def fetch_data() -> bytes:
+            import httpx
+
+            async with httpx.AsyncClient() as http:
+                resp = await http.get(url)
+                resp.raise_for_status()
+                return resp.content
+
+        return fetch_data
+
+    def rehydrate_attachment(self, attachment: Attachment) -> Attachment:
+        """Reconstruct ``fetch_data`` on a deserialized Teams attachment.
+
+        Teams uses public file URLs (signed by the Graph API), so all we
+        need to rebuild the download closure is the URL — either from
+        ``fetch_metadata["url"]`` or the attachment's top-level ``url``.
+        Returns the attachment unchanged when no URL is available.
+        """
+        meta = attachment.fetch_metadata or {}
+        url = meta.get("url") or attachment.url
+        if not url:
+            return attachment
+        return Attachment(
+            type=attachment.type,
+            url=attachment.url,
+            name=attachment.name,
+            mime_type=attachment.mime_type,
+            size=attachment.size,
+            width=attachment.width,
+            height=attachment.height,
+            data=attachment.data,
+            fetch_data=self._build_teams_fetch_data(url),
+            fetch_metadata=attachment.fetch_metadata,
         )
 
     def _is_message_from_self(self, activity: dict[str, Any]) -> bool:

src/chat_sdk/adapters/telegram/adapter.py

@@ -1365,6 +1365,32 @@ def create_attachment(
             name=name,
             mime_type=mime_type,
             fetch_data=lambda _fid=file_id: self.download_file(_fid),
+            fetch_metadata={"fileId": file_id},
+        )
+
+    def rehydrate_attachment(self, attachment: Attachment) -> Attachment:
+        """Reconstruct ``fetch_data`` on a deserialized Telegram attachment.
+
+        Pulls ``fileId`` from ``fetch_metadata`` and rebuilds the lazy
+        ``download_file`` closure.  Returns the attachment unchanged when
+        no file ID is present (e.g. a pre-serialized attachment that did
+        not originate from this adapter).
+        """
+        meta = attachment.fetch_metadata or {}
+        file_id = meta.get("fileId")
+        if not file_id:
+            return attachment
+        return Attachment(
+            type=attachment.type,
+            url=attachment.url,
+            name=attachment.name,
+            mime_type=attachment.mime_type,
+            size=attachment.size,
+            width=attachment.width,
+            height=attachment.height,
+            data=attachment.data,
+            fetch_data=lambda _fid=file_id: self.download_file(_fid),
+            fetch_metadata=attachment.fetch_metadata,
         )
 
     async def download_file(self, file_id: str) -> bytes: