feat: finalize matrix platform audit and docs

sdk/real.py

@@ -2,11 +2,19 @@ from __future__ import annotations
 
 import asyncio
 import inspect
+from collections.abc import AsyncIterator
 from pathlib import Path
-from typing import AsyncIterator
 
 from sdk.agent_api_wrapper import AgentApiWrapper
-from sdk.interface import Attachment, MessageChunk, MessageResponse, PlatformClient, User, UserSettings
+from sdk.interface import (
+    Attachment,
+    MessageChunk,
+    MessageResponse,
+    PlatformClient,
+    PlatformError,
+    User,
+    UserSettings,
+)
 from sdk.prototype_state import PrototypeStateStore
 
 
@@ -83,19 +91,24 @@ class RealPlatformClient(PlatformClient):
             if hasattr(chat_api, "last_tokens_used"):
                 chat_api.last_tokens_used = 0
 
-            async for event in self._stream_agent_events(chat_api, text, attachments=attachments):
-                message_id = user_id
-                if self._is_text_event(event):
-                    chunk_text = getattr(event, "text", "")
-                    if chunk_text:
-                        response_parts.append(chunk_text)
-                elif self._is_end_event(event):
-                    tokens_used = getattr(event, "tokens_used", tokens_used)
-                    saw_end_event = True
-                elif self._is_send_file_event(event):
-                    attachment = self._attachment_from_send_file_event(event)
-                    if attachment is not None:
-                        sent_attachments.append(attachment)
+            try:
+                async for event in self._stream_agent_events(
+                    chat_api, text, attachments=attachments
+                ):
+                    message_id = user_id
+                    if self._is_text_event(event):
+                        chunk_text = getattr(event, "text", "")
+                        if chunk_text:
+                            response_parts.append(chunk_text)
+                    elif self._is_end_event(event):
+                        tokens_used = getattr(event, "tokens_used", tokens_used)
+                        saw_end_event = True
+                    elif self._is_send_file_event(event):
+                        attachment = self._attachment_from_send_file_event(event)
+                        if attachment is not None:
+                            sent_attachments.append(attachment)
+            except Exception as exc:
+                await self._handle_chat_api_failure(chat_id, exc)
 
             if not saw_end_event:
                 tokens_used = getattr(chat_api, "last_tokens_used", tokens_used)
@@ -124,27 +137,32 @@ class RealPlatformClient(PlatformClient):
             if hasattr(chat_api, "last_tokens_used"):
                 chat_api.last_tokens_used = 0
             saw_end_event = False
-            async for event in self._stream_agent_events(chat_api, text, attachments=attachments):
-                if self._is_text_event(event):
-                    yield MessageChunk(
-                        message_id=user_id,
-                        delta=getattr(event, "text", ""),
-                        finished=False,
-                    )
-                elif self._is_end_event(event):
-                    tokens_used = getattr(event, "tokens_used", 0)
-                    saw_end_event = True
-                    await self._prototype_state.set_last_tokens_used(str(chat_id), tokens_used)
-                    yield MessageChunk(
-                        message_id=user_id,
-                        delta="",
-                        finished=True,
-                        tokens_used=tokens_used,
-                    )
-                elif self._is_send_file_event(event):
-                    continue
-                else:
-                    continue
+            try:
+                async for event in self._stream_agent_events(
+                    chat_api, text, attachments=attachments
+                ):
+                    if self._is_text_event(event):
+                        yield MessageChunk(
+                            message_id=user_id,
+                            delta=getattr(event, "text", ""),
+                            finished=False,
+                        )
+                    elif self._is_end_event(event):
+                        tokens_used = getattr(event, "tokens_used", 0)
+                        saw_end_event = True
+                        await self._prototype_state.set_last_tokens_used(str(chat_id), tokens_used)
+                        yield MessageChunk(
+                            message_id=user_id,
+                            delta="",
+                            finished=True,
+                            tokens_used=tokens_used,
+                        )
+                    elif self._is_send_file_event(event):
+                        continue
+                    else:
+                        continue
+            except Exception as exc:
+                await self._handle_chat_api_failure(chat_id, exc)
             if not saw_end_event:
                 tokens_used = getattr(chat_api, "last_tokens_used", 0)
                 await self._prototype_state.set_last_tokens_used(str(chat_id), tokens_used)
@@ -197,6 +215,11 @@ class RealPlatformClient(PlatformClient):
         async for event in event_stream:
             yield event
 
+    async def _handle_chat_api_failure(self, chat_id: str, exc: Exception) -> None:
+        await self.disconnect_chat(chat_id)
+        code = getattr(exc, "code", None) or "PLATFORM_CONNECTION_ERROR"
+        raise PlatformError(str(exc), code=code) from exc
+
     @staticmethod
     def _attachment_paths(attachments: list[Attachment] | None) -> list[str]:
         if not attachments:
@@ -265,7 +288,7 @@ class RealPlatformClient(PlatformClient):
         size = getattr(event, "size", None)
         workspace_path = location
         if workspace_path.startswith("/workspace/"):
-            workspace_path = workspace_path[len("/workspace/"):]
+            workspace_path = workspace_path[len("/workspace/") :]
         elif workspace_path == "/workspace":
             workspace_path = ""
         return Attachment(