wip: 04-matrix-mvp-shared-agent-context-and-context-management-comma paused at task 3/3

.planning/HANDOFF.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0",
-  "timestamp": "2026-04-21T22:33:11.666Z",
+  "timestamp": "2026-04-23T11:46:45.938Z",
   "phase": "04",
   "phase_name": "Matrix MVP: shared agent context and context management commands",
   "phase_dir": ".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma",
@@ -17,91 +17,74 @@
     },
     {
       "id": 2,
-      "name": "Перевести transport layer на thin adapter над pinned upstream AgentApi и обновить тесты/документацию",
+      "name": "Локализовать missing-first-chunk bug, оформить финальный bug report и очистить runtime до thin upstream integration boundary",
       "status": "done",
       "commit": "0c2884c"
     },
     {
       "id": 3,
-      "name": "Провести финальную локализацию streaming bug и зафиксировать platform-side diagnosis в подробном отчёте",
+      "name": "Перейти на direct upstream AgentApi per request, убрать local wrapper из prod path и зафиксировать AGENT_BASE_URL как основной runtime contract",
       "status": "done",
-      "commit": "0c2884c"
+      "commit": "7d58dd1"
     }
   ],
   "remaining_tasks": [
     {
       "id": 4,
-      "name": "Передать платформенной команде финальный bug report и дождаться triage/fix proposal",
+      "name": "Решить, закрываем ли Phase 04 окончательно или продолжаем Matrix через live smoke в реальном окружении",
       "status": "not_started"
     },
     {
       "id": 5,
-      "name": "После ответа платформы решить follow-up phase для surfaces hardening: tokens_used optional, bounded session cache, import/config cleanup, protocol contract tests",
+      "name": "Если двигаемся дальше по Matrix, прогнать text/tool/file smoke на direct AgentApi per-request path и проверить отсутствие regressions",
       "status": "not_started"
     },
     {
       "id": 6,
-      "name": "После platform fix повторно прогнать Matrix live smoke на text/tool/file/image сценариях",
+      "name": "Если начинаем новую surface, открыть follow-up phase для prod messenger architecture без собственного transport layer",
       "status": "not_started"
     }
   ],
   "blockers": [
     {
-      "description": "После tool/file flow начало ответа может пропадать; raw logs показывают, что первый повреждённый MsgEventTextChunk уже рождается внутри platform-agent до websocket-клиента",
-      "type": "external",
-      "workaround": "Только документирование и platform bug report; локально больше не лечить transport hacks"
-    },
-    {
-      "description": "platform-agent отправляет duplicate END",
-      "type": "external",
-      "workaround": "Не чинить в surfaces; держать как известный platform-side дефект до upstream исправления"
-    },
-    {
-      "description": "Image path падает на больших data URI (>10 MB) и сопровождается WS 1009",
-      "type": "external",
-      "workaround": "Удалять oversized staged attachments и предупреждать пользователя; root fix только на платформе"
-    },
-    {
-      "description": "tokens_used остаётся 0, потому что pinned platform-agent_api.AgentApi не публикует MsgEventEnd наружу",
-      "type": "external",
-      "workaround": "Считать текущее значение неизвестным; не городить локальные костыли"
+      "description": "В worktree остаётся посторонний локальный diff в core/handlers/message.py, не связанный с direct AgentApi fix",
+      "type": "technical",
+      "workaround": "Не смешивать с runtime/surface работой без отдельной задачи; handoff commit этот файл не включает"
     }
   ],
   "human_actions_pending": [
     {
-      "action": "Отправить платформенной команде финальный отчёт docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md",
-      "context": "Это основной артефакт с итоговым аудиторским выводом и raw evidence",
-      "blocking": true
+      "action": "Выбрать следующий трек: Matrix live validation или планирование новой prod surface вроде Telegram/Max",
+      "context": "Кодовый фикс уже сделан и запушен; дальше работа зависит от продуктового направления, а не от transport-debug",
+      "blocking": false
     },
     {
-      "action": "Решить, оформлять ли отдельную follow-up phase в roadmap под production cleanup surfaces после platform triage",
-      "context": "Сейчас реализация признана рабочей, но проблемной; часть hardening-задач осознанно отложена",
+      "action": "При следующем отдельном planning/cleanup коммите привести STATE/roadmap в полное соответствие с direct upstream per-request решением",
+      "context": "Локальный STATE уже обновлён как checkpoint, но handoff WIP commit включает только HANDOFF и .continue-here",
       "blocking": false
     }
   ],
   "decisions": [
     {
-      "decision": "Не патчить vendored platform repos для рабочей реализации; все platform-side изменения использовались только как временная локальная диагностика и были откатаны",
-      "rationale": "Нужна чистая граница ответственности между surfaces и платформой",
+      "decision": "Для prod path Matrix surface больше не держит собственный transport layer; используется прямой upstream AgentApi с fresh connection per request",
+      "rationale": "Это убрало reuse-sensitive загрязнение между запросами, после чего missing-first-chunk симптом перестал воспроизводиться локально",
       "phase": "04"
     },
     {
-      "decision": "Оставить transport layer максимально thin: AgentApiWrapper только строит клиента на chat_id, а stream semantics принадлежат upstream AgentApi",
-      "rationale": "Так проще локализовать баги и не смешивать platform bugs с локальными workaround’ами",
+      "decision": "AGENT_BASE_URL принят как основной runtime contract; AGENT_WS_URL оставлен только как backward-compat fallback в env wiring",
+      "rationale": "Так surface говорит с платформой по их реальному API contract, а не через локальный ws shim",
       "phase": "04"
     },
     {
-      "decision": "Считать текущую Matrix real integration рабочей, но проблемной из-за upstream streaming/image bugs",
-      "rationale": "Live flow в целом работает, однако после tool/file path есть подтверждённые platform-side дефекты",
-      "phase": "04"
-    },
-    {
-      "decision": "Не лечить missing-first-chunk локальными transport hacks повторно",
-      "rationale": "После cleanup и raw tracing корень локализован на стороне platform-agent; дальнейшие локальные обходы только размоют диагностику",
+      "decision": "Для следующих surfaces не строить custom transport wrapper поверх платформы",
+      "rationale": "Surface должна владеть integration/session boundary, а не альтернативной stream semantics",
       "phase": "04"
     }
   ],
-  "uncommitted_files": [],
-  "next_action": "Начать с отправки финального bug report платформенной команде; до их triage не менять transport semantics в surfaces повторно",
-  "context_notes": "Сессия завершилась полной очисткой transport layer до thin adapter, обновлением README, финальным bug report и подтверждением через raw logs, что повреждённый первый chunk рождается внутри platform-agent до websocket-клиента. Рабочая ветка clean, последние meaningful commits: 0c2884c и 4524a6a. Если продолжать работу в surfaces без ответа платформы, единственный разумный фронт — инфраструктурный hardening вокруг known limitations, а не ещё одна попытка локально чинить поток."
+  "uncommitted_files": [
+    ".planning/STATE.md",
+    "core/handlers/message.py"
+  ],
+  "next_action": "При возобновлении сначала прочитать обновлённый handoff, затем выбрать один из двух треков: либо Matrix live smoke на direct AgentApi per-request path, либо новая phase/spec для prod surface без собственного transport layer",
+  "context_notes": "Старый checkpoint про platform triage устарел. После диалога с платформой runtime переведён на прямой upstream AgentApi с fresh connection per request, локальный wrapper убран из prod path, tests прошли, commit 7d58dd1 запушен в origin/feat/matrix-direct-agent-prototype. Важный вывод для будущей архитектуры surfaces: upstream transport считать authoritative, а локально держать только lifecycle, serialization, attachment forwarding, error mapping и reconciliation."
 }