feat: support shared-workspace file flow for matrix

tests/adapter/matrix/test_converter.py

@@ -53,6 +53,24 @@ def content_file_event():
     )
 
 
+def source_only_content_file_event():
+    return SimpleNamespace(
+        sender="@a:m.org",
+        body="doc.pdf",
+        event_id="$e5",
+        msgtype=None,
+        replyto_event_id=None,
+        source={
+            "content": {
+                "msgtype": "m.file",
+                "body": "source-only.pdf",
+                "url": "mxc://x/source-only",
+                "info": {"mimetype": "application/pdf"},
+            }
+        },
+    )
+
+
 def test_plain_text_to_incoming_message():
     result = from_room_event(text_event("Hello"), room_id="!r:m.org", chat_id="C1")
     assert isinstance(result, IncomingMessage)
@@ -147,5 +165,15 @@ def test_attachment_falls_back_to_content_payload():
     assert a.mime_type == "application/pdf"
 
 
+def test_attachment_falls_back_to_source_content_payload():
+    result = from_room_event(source_only_content_file_event(), room_id="!r:m.org", chat_id="C1")
+    assert isinstance(result, IncomingMessage)
+    a = result.attachments[0]
+    assert a.type == "document"
+    assert a.url == "mxc://x/source-only"
+    assert a.filename == "source-only.pdf"
+    assert a.mime_type == "application/pdf"
+
+
 def test_converter_module_does_not_expose_reaction_callbacks():
     assert not hasattr(converter, "from_reaction")

tests/adapter/matrix/test_dispatcher.py

@@ -5,6 +5,13 @@ from types import SimpleNamespace
 from unittest.mock import AsyncMock
 
 import pytest
+from nio import (
+    RoomMessageAudio,
+    RoomMessageFile,
+    RoomMessageImage,
+    RoomMessageText,
+    RoomMessageVideo,
+)
 from nio.api import RoomVisibility
 from nio.responses import SyncResponse
 
@@ -332,7 +339,7 @@ async def test_bot_downloads_matrix_file_to_workspace_before_staging(tmp_path, m
     staged = await get_staged_attachments(runtime.store, "!chat1:example.org", "@alice:example.org")
     assert staged[0]["workspace_path"] is not None
     assert (tmp_path / staged[0]["workspace_path"]).read_bytes() == b"%PDF-1.7"
-    bot._send_all.assert_awaited_once()
+    bot._send_all.assert_not_awaited()
 
 
 async def test_file_only_event_is_staged_and_does_not_dispatch():
@@ -371,10 +378,7 @@ async def test_file_only_event_is_staged_and_does_not_dispatch():
     runtime.dispatcher.dispatch.assert_not_awaited()
     staged = await get_staged_attachments(runtime.store, "!r:example.org", "@alice:example.org")
     assert [item["filename"] for item in staged] == ["report.pdf"]
-    client.room_send.assert_awaited_once()
-    assert (
-        "Следующее сообщение отправит файлы агенту." in client.room_send.await_args.args[2]["body"]
-    )
+    client.room_send.assert_not_awaited()
 
 
 async def test_list_command_returns_current_staged_attachments():
@@ -963,3 +967,43 @@ async def test_matrix_main_closes_platform_without_connecting_root_agent(monkeyp
 
     agent_connect.assert_not_awaited()
     platform_close.assert_awaited_once()
+
+
+async def test_matrix_main_registers_media_message_callbacks(monkeypatch):
+    bot_module = importlib.import_module("adapter.matrix.bot")
+
+    runtime = SimpleNamespace(platform=SimpleNamespace(close=AsyncMock()))
+    created_clients = []
+
+    class FakeAsyncClient:
+        def __init__(self, *args, **kwargs):
+            self.access_token = None
+            self.callbacks = []
+            self.sync_forever = AsyncMock()
+            self.close = AsyncMock()
+            created_clients.append(self)
+
+        async def login(self, *args, **kwargs):
+            raise AssertionError("login should not be called when access token is provided")
+
+        def add_event_callback(self, callback, event_type):
+            self.callbacks.append((callback, event_type))
+
+    monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org")
+    monkeypatch.setenv("MATRIX_USER_ID", "@bot:example.org")
+    monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "token")
+    monkeypatch.setattr(bot_module, "AsyncClient", FakeAsyncClient)
+    monkeypatch.setattr(bot_module, "build_runtime", lambda **kwargs: runtime)
+    monkeypatch.setattr(bot_module, "prepare_live_sync", AsyncMock(return_value="s123"))
+
+    await bot_module.main()
+
+    assert len(created_clients) == 1
+    registered_types = [event_type for _, event_type in created_clients[0].callbacks]
+    assert (
+        RoomMessageText,
+        RoomMessageFile,
+        RoomMessageImage,
+        RoomMessageVideo,
+        RoomMessageAudio,
+    ) in registered_types

tests/adapter/matrix/test_files.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+from adapter.matrix.files import build_workspace_attachment_path, download_matrix_attachment
+from core.protocol import Attachment
+
+
+def test_build_workspace_attachment_path_scopes_by_surface_user_and_room(tmp_path: Path):
+    rel_path, abs_path = build_workspace_attachment_path(
+        workspace_root=tmp_path,
+        matrix_user_id="@alice:example.org",
+        room_id="!room:example.org",
+        filename="report.pdf",
+        timestamp="20260420-153000",
+    )
+
+    assert (
+        rel_path
+        == "surfaces/matrix/alice_example.org/room_example.org/inbox/20260420-153000-report.pdf"
+    )
+    assert abs_path == tmp_path / rel_path
+
+
+async def test_download_matrix_attachment_persists_file_and_returns_workspace_path(tmp_path: Path):
+    async def download(url: str):
+        assert url == "mxc://server/id"
+        return SimpleNamespace(body=b"%PDF-1.7")
+
+    client = SimpleNamespace(download=download)
+    attachment = Attachment(
+        type="document",
+        url="mxc://server/id",
+        filename="report.pdf",
+        mime_type="application/pdf",
+    )
+
+    saved = await download_matrix_attachment(
+        client=client,
+        workspace_root=tmp_path,
+        matrix_user_id="@alice:example.org",
+        room_id="!room:example.org",
+        attachment=attachment,
+        timestamp="20260420-153000",
+    )
+
+    assert saved.workspace_path is not None
+    assert saved.workspace_path.endswith("20260420-153000-report.pdf")
+    assert (tmp_path / saved.workspace_path).read_bytes() == b"%PDF-1.7"

tests/adapter/matrix/test_send_outgoing.py

@@ -9,7 +9,7 @@ from adapter.matrix.handlers.confirm import make_handle_cancel, make_handle_conf
 from adapter.matrix.store import get_pending_confirm, set_room_meta
 from core.auth import AuthManager
 from core.chat import ChatManager
-from core.protocol import OutgoingUI, UIButton
+from core.protocol import Attachment, OutgoingMessage, OutgoingUI, UIButton
 from core.settings import SettingsManager
 from core.store import InMemoryStore
 from sdk.mock import MockPlatformClient
@@ -156,3 +156,39 @@ async def test_outgoing_ui_no_round_trip_uses_user_and_room_scope():
     assert "отменено" in result[0].text.lower()
     assert await get_pending_confirm(store, "@alice:example.org", "!confirm:example.org") is None
     assert await get_pending_confirm(store, "@bob:example.org", "!other:example.org") is not None
+
+
+async def test_send_outgoing_uploads_workspace_file_attachment(tmp_path, monkeypatch):
+    workspace_file = tmp_path / "surfaces" / "matrix" / "alice" / "room" / "inbox" / "result.txt"
+    workspace_file.parent.mkdir(parents=True, exist_ok=True)
+    workspace_file.write_text("ready")
+    monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path))
+
+    client = SimpleNamespace(
+        upload=AsyncMock(return_value=(SimpleNamespace(content_uri="mxc://server/file"), {})),
+        room_send=AsyncMock(),
+    )
+
+    await send_outgoing(
+        client,
+        "!room:example.org",
+        OutgoingMessage(
+            chat_id="!room:example.org",
+            text="Файл готов",
+            attachments=[
+                Attachment(
+                    type="document",
+                    filename="result.txt",
+                    mime_type="text/plain",
+                    workspace_path="surfaces/matrix/alice/room/inbox/result.txt",
+                )
+            ],
+        ),
+    )
+
+    client.upload.assert_awaited_once()
+    client.room_send.assert_awaited()
+    assert client.room_send.await_args_list[0].args[2]["body"] == "Файл готов"
+    file_call = client.room_send.await_args_list[1]
+    assert file_call.args[2]["msgtype"] == "m.file"
+    assert file_call.args[2]["url"] == "mxc://server/file"

tests/core/test_dispatcher.py

@@ -75,6 +75,27 @@ async def test_dispatch_routes_audio_before_catchall(dispatcher):
     assert (await dispatcher.dispatch(text_msg))[0].text == "text"
 
 
+async def test_dispatch_routes_document_before_catchall(dispatcher):
+    async def document_handler(event, **kwargs):
+        return [OutgoingMessage(chat_id=event.chat_id, text="document")]
+
+    async def catch_all(event, **kwargs):
+        return [OutgoingMessage(chat_id=event.chat_id, text="text")]
+
+    dispatcher.register(IncomingMessage, "document", document_handler)
+    dispatcher.register(IncomingMessage, "*", catch_all)
+
+    document_msg = IncomingMessage(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        text="",
+        attachments=[Attachment(type="document", workspace_path="surfaces/matrix/u1/file.pdf")],
+    )
+
+    assert (await dispatcher.dispatch(document_msg))[0].text == "document"
+
+
 async def test_dispatch_callback_by_action(dispatcher):
     async def confirm_handler(event, **kwargs):
         return [OutgoingMessage(chat_id=event.chat_id, text="confirmed")]

tests/core/test_integration.py

@@ -23,11 +23,11 @@ from core.protocol import (
 
 class FakeAgentApi:
     def __init__(self) -> None:
-        self.calls: list[str] = []
+        self.calls: list[tuple[str, list[str]]] = []
         self.last_tokens_used = 0
 
-    async def send_message(self, text: str):
-        self.calls.append(text)
+    async def send_message(self, text: str, attachments: list[str] | None = None):
+        self.calls.append((text, attachments or []))
         yield type("Chunk", (), {"text": f"[REAL] {text}"})()
         self.last_tokens_used = 5
 
@@ -130,4 +130,31 @@ async def test_full_flow_with_real_platform_uses_shared_agent_api(real_dispatche
     texts = [r.text for r in result if isinstance(r, OutgoingMessage)]
 
     assert texts == ["[REAL] Привет!"]
-    assert agent_api.calls == ["Привет!"]
+    assert agent_api.calls == [("Привет!", [])]
+
+
+async def test_full_flow_with_real_platform_forwards_workspace_attachment(real_dispatcher):
+    dispatcher, agent_api = real_dispatcher
+
+    start = IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="start")
+    await dispatcher.dispatch(start)
+
+    msg = IncomingMessage(
+        user_id="u1",
+        platform="matrix",
+        chat_id="C1",
+        text="Посмотри файл",
+        attachments=[
+            Attachment(
+                type="document",
+                filename="report.pdf",
+                mime_type="application/pdf",
+                workspace_path="surfaces/matrix/u1/room/inbox/report.pdf",
+            )
+        ],
+    )
+    await dispatcher.dispatch(msg)
+
+    assert agent_api.calls == [
+        ("Посмотри файл", ["surfaces/matrix/u1/room/inbox/report.pdf"])
+    ]

tests/platform/test_real.py

@@ -5,7 +5,7 @@ import pytest
 from core.protocol import SettingsAction
 import sdk.agent_api_wrapper as agent_api_wrapper_module
 from sdk.agent_api_wrapper import AgentApiWrapper
-from sdk.interface import MessageChunk, MessageResponse, UserSettings
+from sdk.interface import Attachment, MessageChunk, MessageResponse, UserSettings
 from sdk.prototype_state import PrototypeStateStore
 from sdk.real import RealPlatformClient
 
@@ -90,6 +90,100 @@ class BlockingChatAgentApi:
         self.last_tokens_used = len(text)
 
 
+class AttachmentTrackingChatAgentApi:
+    def __init__(self, chat_id: str) -> None:
+        self.chat_id = chat_id
+        self.calls: list[tuple[str, list[str] | None]] = []
+        self.connect_calls = 0
+        self.close_calls = 0
+        self.last_tokens_used = 0
+
+    async def connect(self) -> None:
+        self.connect_calls += 1
+
+    async def close(self) -> None:
+        self.close_calls += 1
+
+    async def send_message(self, text: str, attachments: list[str] | None = None):
+        self.calls.append((text, attachments))
+        yield FakeChunk(text)
+        self.last_tokens_used = 5
+
+
+class SendFileEvent:
+    def __init__(self, *, workspace_path: str, mime_type: str, filename: str, size: int) -> None:
+        self.type = "AGENT_EVENT_SEND_FILE"
+        self.workspace_path = workspace_path
+        self.mime_type = mime_type
+        self.filename = filename
+        self.size = size
+
+
+class TextChunkEvent:
+    def __init__(self, text: str) -> None:
+        self.type = "AGENT_EVENT_TEXT_CHUNK"
+        self.text = text
+
+
+class ToolCallChunkEvent:
+    def __init__(self, payload: str) -> None:
+        self.type = "AGENT_EVENT_TOOL_CALL_CHUNK"
+        self.payload = payload
+
+
+class ToolResultEvent:
+    def __init__(self, payload: str) -> None:
+        self.type = "AGENT_EVENT_TOOL_RESULT"
+        self.payload = payload
+
+
+class CustomUpdateEvent:
+    def __init__(self, payload: str) -> None:
+        self.type = "AGENT_EVENT_CUSTOM_UPDATE"
+        self.payload = payload
+
+
+class EndEvent:
+    def __init__(self, tokens_used: int) -> None:
+        self.type = "AGENT_EVENT_END"
+        self.tokens_used = tokens_used
+
+
+class ErrorEvent:
+    def __init__(self, code: str, details: str) -> None:
+        self.type = "ERROR"
+        self.code = code
+        self.details = details
+
+
+class GracefulDisconnectEvent:
+    def __init__(self) -> None:
+        self.type = "GRACEFUL_DISCONNECT"
+
+
+class FakeWSMessage:
+    def __init__(self, data: str) -> None:
+        self.type = agent_api_wrapper_module.aiohttp.WSMsgType.TEXT
+        self.data = data
+
+
+class FakeWebSocket:
+    def __init__(self, messages: list[FakeWSMessage]) -> None:
+        self._messages = list(messages)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if not self._messages:
+            raise StopAsyncIteration
+        return self._messages.pop(0)
+
+
+class MessageResponseWithAttachments(MessageResponse):
+    attachments: list[Attachment] = []
+
+
 def test_agent_api_wrapper_uses_modern_constructor_when_available(monkeypatch):
     calls: list[dict[str, object]] = []
 
@@ -219,6 +313,76 @@ async def test_real_platform_client_send_message_uses_chat_bound_client():
     assert await prototype_state.get_last_tokens_used_for_context("chat-7") == 3
 
 
+@pytest.mark.asyncio
+async def test_real_platform_client_forwards_attachments_to_chat_api():
+    agent_api = AttachmentTrackingChatAgentApi("chat-7")
+    client = RealPlatformClient(
+        agent_api=agent_api,
+        prototype_state=PrototypeStateStore(),
+        platform="matrix",
+    )
+    attachment = Attachment(
+        workspace_path="surfaces/matrix/alice/room/inbox/report.pdf",
+        mime_type="application/pdf",
+        filename="report.pdf",
+        size=123,
+    )
+
+    result = await client.send_message(
+        "@alice:example.org",
+        "chat-7",
+        "hello",
+        attachments=[attachment],
+    )
+
+    assert agent_api.calls == [("hello", ["surfaces/matrix/alice/room/inbox/report.pdf"])]
+    assert result.response == "hello"
+    assert result.tokens_used == 5
+
+
+@pytest.mark.asyncio
+async def test_real_platform_client_preserves_send_file_events_in_sync_result(monkeypatch):
+    agent_api = AttachmentTrackingChatAgentApi("chat-7")
+    client = RealPlatformClient(
+        agent_api=agent_api,
+        prototype_state=PrototypeStateStore(),
+        platform="matrix",
+    )
+
+    class FileEventAgentApi(AttachmentTrackingChatAgentApi):
+        async def send_message(self, text: str, attachments: list[str] | None = None):
+            self.calls.append((text, attachments))
+            yield TextChunkEvent("he")
+            yield SendFileEvent(
+                workspace_path="/workspace/report.pdf",
+                mime_type="application/pdf",
+                filename="report.pdf",
+                size=123,
+            )
+            yield TextChunkEvent("llo")
+            self.last_tokens_used = 9
+
+    monkeypatch.setattr(
+        "sdk.real.MessageResponse",
+        MessageResponseWithAttachments,
+    )
+    client._agent_api = FileEventAgentApi("chat-7")
+
+    result = await client.send_message("@alice:example.org", "chat-7", "hello")
+
+    assert result.response == "hello"
+    assert result.tokens_used == 9
+    assert result.attachments == [
+        Attachment(
+            url="/workspace/report.pdf",
+            mime_type="application/pdf",
+            filename="report.pdf",
+            size=123,
+            workspace_path="report.pdf",
+        )
+    ]
+
+
 @pytest.mark.asyncio
 async def test_real_platform_client_works_with_legacy_agent_api_without_for_chat():
     legacy_api = LegacyAgentApi()
@@ -385,3 +549,85 @@ async def test_real_platform_client_settings_are_local():
     assert isinstance(settings, UserSettings)
     assert settings.skills["browser"] is True
     assert settings.skills["web-search"] is True
+
+
+@pytest.mark.asyncio
+async def test_agent_api_wrapper_transparently_surfaces_modern_events(monkeypatch):
+    callback_events: list[object] = []
+    queue: asyncio.Queue = asyncio.Queue()
+    event_map = {
+        "text": TextChunkEvent("he"),
+        "tool_call": ToolCallChunkEvent("call"),
+        "tool_result": ToolResultEvent("result"),
+        "custom_update": CustomUpdateEvent("update"),
+        "send_file": SendFileEvent(
+            workspace_path="/workspace/report.pdf",
+            mime_type="application/pdf",
+            filename="report.pdf",
+            size=123,
+        ),
+        "end": EndEvent(tokens_used=11),
+        "error": ErrorEvent(code="BOOM", details="bad things"),
+        "disconnect": GracefulDisconnectEvent(),
+    }
+
+    def fake_validate_json(data: str):
+        return event_map[data]
+
+    monkeypatch.setattr(
+        agent_api_wrapper_module,
+        "ServerMessage",
+        type("FakeServerMessage", (), {"validate_json": staticmethod(fake_validate_json)}),
+    )
+
+    async def fake_cleanup(self):
+        return None
+
+    monkeypatch.setattr(agent_api_wrapper_module.AgentApiWrapper, "_cleanup", fake_cleanup)
+    monkeypatch.setattr(
+        agent_api_wrapper_module.AgentApi,
+        "__init__",
+        lambda self, agent_id, base_url=None, chat_id=0, **kwargs: setattr(self, "id", agent_id)
+        or setattr(self, "callback", kwargs.get("callback"))
+        or setattr(self, "on_disconnect", kwargs.get("on_disconnect"))
+        or setattr(self, "_current_queue", None),
+    )
+
+    wrapper = AgentApiWrapper(
+        agent_id="agent-1",
+        base_url="https://agent.example.com/v1/agent_ws",
+        chat_id="chat-1",
+        callback=callback_events.append,
+    )
+    wrapper._current_queue = queue
+    wrapper._ws = FakeWebSocket(
+        [
+            FakeWSMessage("text"),
+            FakeWSMessage("tool_call"),
+            FakeWSMessage("tool_result"),
+            FakeWSMessage("custom_update"),
+            FakeWSMessage("send_file"),
+            FakeWSMessage("end"),
+            FakeWSMessage("error"),
+            FakeWSMessage("disconnect"),
+        ]
+    )
+
+    await wrapper._listen()
+
+    queue_events = []
+    while not queue.empty():
+        queue_events.append(await queue.get())
+
+    assert queue_events[0].text == "he"
+    assert any(isinstance(event, SendFileEvent) for event in queue_events)
+    assert any(isinstance(event, EndEvent) for event in queue_events)
+    assert any(isinstance(event, GracefulDisconnectEvent) for event in queue_events)
+    assert callback_events[0].payload == "call"
+    assert callback_events[1].payload == "result"
+    assert callback_events[2].payload == "update"
+    assert any(isinstance(event, SendFileEvent) for event in callback_events)
+    assert any(isinstance(event, EndEvent) for event in callback_events)
+    assert any(isinstance(event, ErrorEvent) for event in callback_events)
+    assert any(isinstance(event, GracefulDisconnectEvent) for event in callback_events)
+    assert wrapper.last_tokens_used == 11