feat(teams): deliver outbound files via data-URI activity attachments

Port upstream filesToAttachments (packages/adapter-teams/src/index.ts
~1006-1035) to Python. The Teams adapter previously dropped a Postable's
.files entirely -- post_message/edit_message never called extract_files,
so execution artifacts silently vanished.

Adds TeamsAdapter._files_to_attachments: resolves each FileUpload's bytes
via to_buffer(..., throw_on_unsupported=False), base64-encodes them, and
builds a Bot Framework attachment {contentType, contentUrl:
data:<mime>;base64,<b64>, name}. mime defaults to
application/octet-stream; files whose data can't be resolved to bytes are
skipped with a debug log (mirrors upstream's `if (!buffer) continue`).

post_message and edit_message now call extract_files and attach the
results: the adaptive-card branch appends file attachments after the card
attachment; the text branch sets attachments to the file attachments when
present.

Adds TestFileAttachments (5 tests): text+file, card+file (both
attachments present), edit_message+file, octet-stream default, and the
skip-unresolvable-bytes branch.

Bumps version to 0.4.29a3 and adds a CHANGELOG entry.

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

Author: patrick-chinchill

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.29a3 (2026-05-29)
+
+Python-only feature port. No upstream version change.
+
+### Features
+
+- **Teams now delivers outbound files via base64 data-URI activity attachments** — the Teams adapter previously dropped a `Postable`'s `.files` entirely: `post_message`/`edit_message` never called `extract_files`, so execution artifacts (CSVs, charts, etc.) silently vanished. This ports upstream `vercel/chat`'s `filesToAttachments` (`packages/adapter-teams/src/index.ts` lines ~1006-1035) to Python. A new `TeamsAdapter._files_to_attachments` resolves each `FileUpload`'s bytes via `to_buffer(..., throw_on_unsupported=False)`, base64-encodes them, and builds a Bot Framework attachment `{"contentType", "contentUrl": "data:<mime>;base64,<b64>", "name"}` (mime defaults to `application/octet-stream`); files whose data can't be resolved to bytes are skipped with a debug log (mirrors upstream's `if (!buffer) continue`). `post_message` and `edit_message` now call `extract_files` and attach the results: the adaptive-card branch appends file attachments after the card attachment, and the text branch sets `attachments` to the file attachments when present. This is the Teams half of outbound artifact parity and unblocks chinchill routing execution artifacts to Teams. **Caveat (inherited from upstream's design):** data-URI attachments inline the full file payload base64-encoded in the activity, so large files inflate the Bot Framework payload — the same size constraint upstream carries.
+
+### Test quality
+
+- Added 5 tests in `tests/test_teams_adapter.py` (`TestFileAttachments`): text+file, adaptive-card+file (both attachments present), `edit_message`+file, mime-type default to `application/octet-stream`, and the skip-unresolvable-bytes branch. Each delivery test round-trips or asserts the `data:<mime>;base64,...` `contentUrl`, `contentType`, and `name`.
+
 ## 0.4.29a2 (2026-05-28)
 
 Python-only fix. No upstream version change.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chat-sdk"
-version = "0.4.29a2"
+version = "0.4.29a3"
 description = "Multi-platform async chat SDK for Python — port of Vercel Chat"
 keywords = [
     "chat",

src/chat_sdk/adapters/teams/adapter.py

@@ -31,7 +31,8 @@
 from chat_sdk.emoji import convert_emoji_placeholders
 from chat_sdk.errors import ChatNotImplementedError
 from chat_sdk.logger import ConsoleLogger, Logger
-from chat_sdk.shared.adapter_utils import extract_card
+from chat_sdk.shared.adapter_utils import extract_card, extract_files
+from chat_sdk.shared.buffer_utils import buffer_to_data_uri, to_buffer
 from chat_sdk.shared.errors import (
     AdapterPermissionError,
     AdapterRateLimitError,
@@ -49,6 +50,7 @@
     EmojiValue,
     FetchOptions,
     FetchResult,
+    FileUpload,
     FormattedContent,
     LockScope,
     Message,
@@ -1038,6 +1040,40 @@ def _is_message_from_self(self, activity: dict[str, Any]) -> bool:
             return True
         return bool(from_id.endswith(f":{self._app_id}"))
 
+    async def _files_to_attachments(self, files: list[FileUpload]) -> list[dict[str, Any]]:
+        """Convert ``FileUpload`` objects to Bot Framework data-URI attachments.
+
+        Python port of ``filesToAttachments`` in
+        ``packages/adapter-teams/src/index.ts`` (lines ~1006-1035). Each file's
+        bytes are base64-encoded into a ``data:`` URI and attached as a
+        Bot Framework activity attachment. Files whose data cannot be resolved
+        to bytes are skipped (mirrors upstream's ``throwOnUnsupported: false``
+        followed by ``if (!buffer) continue``).
+        """
+        attachments: list[dict[str, Any]] = []
+
+        for file in files:
+            buffer = await to_buffer(file.data, "teams", throw_on_unsupported=False)
+            if buffer is None:
+                self._logger.debug(
+                    "Teams API: skipping file with unsupported data",
+                    {"filename": file.filename},
+                )
+                continue
+
+            mime_type = file.mime_type or "application/octet-stream"
+            data_uri = buffer_to_data_uri(buffer, mime_type)
+
+            attachments.append(
+                {
+                    "contentType": mime_type,
+                    "contentUrl": data_uri,
+                    "name": file.filename,
+                }
+            )
+
+        return attachments
+
     async def post_message(
         self,
         thread_id: str,
@@ -1046,6 +1082,9 @@ async def post_message(
         """Post a message to a Teams conversation."""
         decoded = self.decode_thread_id(thread_id)
 
+        files = extract_files(message)
+        file_attachments = await self._files_to_attachments(files) if files else []
+
         card = extract_card(message)
         if card:
             adaptive_card = card_to_adaptive_card(card)
@@ -1055,14 +1094,16 @@ async def post_message(
                     {
                         "contentType": "application/vnd.microsoft.card.adaptive",
                         "content": adaptive_card,
-                    }
+                    },
+                    *file_attachments,
                 ],
             }
 
             self._logger.debug(
                 "Teams API: send (adaptive card)",
                 {
                     "conversationId": decoded.conversation_id,
+                    "fileCount": len(file_attachments),
                 },
             )
 
@@ -1089,17 +1130,20 @@ async def post_message(
             "teams",
         )
 
-        activity_payload = {
+        activity_payload: dict[str, Any] = {
             "type": "message",
             "text": text,
             "textFormat": "markdown",
         }
+        if file_attachments:
+            activity_payload["attachments"] = file_attachments
 
         self._logger.debug(
             "Teams API: send (message)",
             {
                 "conversationId": decoded.conversation_id,
                 "textLength": len(text),
+                "fileCount": len(file_attachments),
             },
         )
 
@@ -1130,7 +1174,11 @@ async def edit_message(
         """Edit an existing Teams message."""
         decoded = self.decode_thread_id(thread_id)
 
+        files = extract_files(message)
+        file_attachments = await self._files_to_attachments(files) if files else []
+
         card = extract_card(message)
+        activity_payload: dict[str, Any]
         if card:
             adaptive_card = card_to_adaptive_card(card)
             activity_payload = {
@@ -1139,7 +1187,8 @@ async def edit_message(
                     {
                         "contentType": "application/vnd.microsoft.card.adaptive",
                         "content": adaptive_card,
-                    }
+                    },
+                    *file_attachments,
                 ],
             }
         else:
@@ -1152,6 +1201,8 @@ async def edit_message(
                 "text": text,
                 "textFormat": "markdown",
             }
+            if file_attachments:
+                activity_payload["attachments"] = file_attachments
 
         self._logger.debug(
             "Teams API: updateActivity",

tests/test_teams_adapter.py

@@ -694,6 +694,140 @@ async def test_updates_and_returns(self):
         adapter._teams_update.assert_called_once()
 
 
+class TestFileAttachments:
+    """Outbound file delivery via base64 data-URI activity attachments.
+
+    Ports ``filesToAttachments`` from
+    ``packages/adapter-teams/src/index.ts`` (lines ~1006-1035) and its use in
+    ``postMessage``/``editMessage``.
+    """
+
+    @staticmethod
+    def _thread_id(adapter: TeamsAdapter) -> str:
+        return adapter.encode_thread_id(
+            TeamsThreadId(
+                conversation_id="19:abc@thread.tacv2",
+                service_url="https://smba.trafficmanager.net/teams/",
+            )
+        )
+
+    @pytest.mark.asyncio
+    async def test_text_message_with_file(self):
+        from chat_sdk.types import FileUpload, PostableMarkdown
+
+        adapter = _make_adapter(app_id="test-app-id", logger=_make_logger())
+        adapter._teams_send = AsyncMock(return_value={"id": "sent-1", "type": "message"})
+
+        message = PostableMarkdown(
+            markdown="here is your report",
+            files=[FileUpload(data=b"a,b,c\n1,2,3\n", filename="report.csv", mime_type="text/csv")],
+        )
+        result = await adapter.post_message(self._thread_id(adapter), message)
+
+        payload = adapter._teams_send.call_args.args[1]
+        attachments = payload["attachments"]
+        assert len(attachments) == 1
+        att = attachments[0]
+        assert att["contentType"] == "text/csv"
+        assert att["name"] == "report.csv"
+        assert att["contentUrl"].startswith("data:text/csv;base64,")
+        # round-trip the base64 payload back to the original bytes
+        import base64
+
+        b64 = att["contentUrl"].split("base64,", 1)[1]
+        assert base64.b64decode(b64) == b"a,b,c\n1,2,3\n"
+        # the data-URI attachment is also recorded on the returned raw activity
+        assert result.raw["attachments"][0]["name"] == "report.csv"
+
+    @pytest.mark.asyncio
+    async def test_card_message_with_file(self):
+        from chat_sdk.cards import Card
+        from chat_sdk.types import FileUpload, PostableCard
+
+        adapter = _make_adapter(app_id="test-app-id", logger=_make_logger())
+        adapter._teams_send = AsyncMock(return_value={"id": "sent-2", "type": "message"})
+
+        message = PostableCard(
+            card=Card(title="Results"),
+            files=[FileUpload(data=b"\x89PNG\r\n", filename="chart.png", mime_type="image/png")],
+        )
+        await adapter.post_message(self._thread_id(adapter), message)
+
+        payload = adapter._teams_send.call_args.args[1]
+        attachments = payload["attachments"]
+        # adaptive card attachment AND the file attachment both present
+        assert len(attachments) == 2
+        assert attachments[0]["contentType"] == "application/vnd.microsoft.card.adaptive"
+        file_att = attachments[1]
+        assert file_att["contentType"] == "image/png"
+        assert file_att["name"] == "chart.png"
+        assert file_att["contentUrl"].startswith("data:image/png;base64,")
+
+    @pytest.mark.asyncio
+    async def test_edit_message_with_file(self):
+        from chat_sdk.types import FileUpload, PostableMarkdown
+
+        adapter = _make_adapter(app_id="test-app-id", logger=_make_logger())
+        adapter._teams_update = AsyncMock()
+
+        message = PostableMarkdown(
+            markdown="updated",
+            files=[FileUpload(data=b"hello", filename="note.txt", mime_type="text/plain")],
+        )
+        result = await adapter.edit_message(self._thread_id(adapter), "edit-1", message)
+
+        payload = adapter._teams_update.call_args.args[2]
+        attachments = payload["attachments"]
+        assert len(attachments) == 1
+        assert attachments[0]["contentType"] == "text/plain"
+        assert attachments[0]["name"] == "note.txt"
+        assert attachments[0]["contentUrl"].startswith("data:text/plain;base64,")
+        assert result.id == "edit-1"
+
+    @pytest.mark.asyncio
+    async def test_file_without_mime_type_defaults_to_octet_stream(self):
+        from chat_sdk.types import FileUpload, PostableMarkdown
+
+        adapter = _make_adapter(app_id="test-app-id", logger=_make_logger())
+        adapter._teams_send = AsyncMock(return_value={"id": "sent-3", "type": "message"})
+
+        message = PostableMarkdown(
+            markdown="bin",
+            files=[FileUpload(data=b"\x00\x01\x02", filename="blob.bin")],
+        )
+        await adapter.post_message(self._thread_id(adapter), message)
+
+        att = adapter._teams_send.call_args.args[1]["attachments"][0]
+        assert att["contentType"] == "application/octet-stream"
+        assert att["contentUrl"].startswith("data:application/octet-stream;base64,")
+
+    @pytest.mark.asyncio
+    async def test_file_with_unresolvable_data_is_skipped(self):
+        """A FileUpload whose data is not bytes is skipped with a debug log.
+
+        Mirrors upstream's ``throwOnUnsupported: false`` followed by
+        ``if (!buffer) continue``. (The Python ``FileUpload`` has no
+        ``fetch_data`` field — it carries only inline ``data`` bytes — so the
+        lazy-fetch case from the upstream interface collapses to this
+        skip-unresolvable-bytes branch.)
+        """
+        from chat_sdk.types import FileUpload, PostableMarkdown
+
+        logger = _make_logger()
+        adapter = _make_adapter(app_id="test-app-id", logger=logger)
+        adapter._teams_send = AsyncMock(return_value={"id": "sent-4", "type": "message"})
+
+        # data is a str, not bytes -> to_buffer returns None -> file skipped
+        bad = FileUpload(data="not-bytes", filename="bad.txt", mime_type="text/plain")  # type: ignore[arg-type]
+        message = PostableMarkdown(markdown="text only", files=[bad])
+        await adapter.post_message(self._thread_id(adapter), message)
+
+        payload = adapter._teams_send.call_args.args[1]
+        # no attachments key added when every file was skipped
+        assert "attachments" not in payload
+        assert logger.debug.called
+
+
 class TestDeleteMessage:
     @pytest.mark.asyncio
     async def test_deletes_without_error(self):