feat: extend platform mock + add research docs

platform/interface.py:
- Add Attachment, MessageChunk, AgentEvent types
- Add stream_message() to PlatformClient Protocol (door open for streaming)
- Add WebhookReceiver Protocol

platform/mock.py:
- Add attachment_mode config (url/binary/s3)
- Implement stream_message() — single chunk, ready for real streaming
- Add register_webhook_receiver() + simulate_agent_event() for testing

docs/research/:
- telegram-forum-topics.md — aiogram 3.x Forum Topics API, FSM patterns, UX analysis
- fsm-patterns.md — FSM storage options, StateData best practices
- matrix-spaces.md — matrix-nio Space API, room ordering, invite flow
- matrix-events.md — reactions, threads, typing, sync loop pitfalls
- telegram-chat-alternatives.md — 7 alternatives for multi-chat UX, virtual chats in DM recommended

platform/interface.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any, Protocol
+from typing import Any, AsyncIterator, Literal, Protocol
 
 from pydantic import BaseModel
 
@@ -16,6 +16,13 @@ class User(BaseModel):
     is_new: bool = False
 
 
+class Attachment(BaseModel):
+    url: str
+    mime_type: str
+    size: int | None = None
+    filename: str | None = None
+
+
 class MessageResponse(BaseModel):
     message_id: str
     response: str
@@ -23,6 +30,14 @@ class MessageResponse(BaseModel):
     finished: bool
 
 
+class MessageChunk(BaseModel):
+    """Один кусок стримингового ответа. При sync-режиме — единственный чанк с finished=True."""
+    message_id: str
+    delta: str
+    finished: bool
+    tokens_used: int = 0
+
+
 class UserSettings(BaseModel):
     skills: dict[str, bool] = {}
     connectors: dict[str, dict] = {}
@@ -31,6 +46,15 @@ class UserSettings(BaseModel):
     plan: dict[str, Any] = {}
 
 
+class AgentEvent(BaseModel):
+    """Webhook-уведомление от платформы — агент закончил долгую задачу."""
+    event_id: str
+    user_id: str
+    chat_id: str
+    event_type: Literal["task_done", "task_error", "task_progress"]
+    payload: dict[str, Any] = {}
+
+
 class PlatformError(Exception):
     def __init__(self, message: str, code: str = "PLATFORM_ERROR"):
         super().__init__(message)
@@ -45,15 +69,29 @@ class PlatformClient(Protocol):
         display_name: str | None = None,
     ) -> User: ...
 
-    # Master manages container lifecycle — bot only sends user_id + chat_id.
+    # Sync — используем сейчас
     async def send_message(
         self,
         user_id: str,
         chat_id: str,
         text: str,
-        attachments: list | None = None,
+        attachments: list[Attachment] | None = None,
     ) -> MessageResponse: ...
 
+    # Streaming — дверь открыта, мок отдаёт один чанк
+    async def stream_message(
+        self,
+        user_id: str,
+        chat_id: str,
+        text: str,
+        attachments: list[Attachment] | None = None,
+    ) -> AsyncIterator[MessageChunk]: ...
+
     async def get_settings(self, user_id: str) -> UserSettings: ...
 
     async def update_settings(self, user_id: str, action: Any) -> None: ...
+
+
+class WebhookReceiver(Protocol):
+    """Регистрируется в боте. Платформа зовёт нас когда агент закончил долгую задачу."""
+    async def on_agent_event(self, event: AgentEvent) -> None: ...