surfaces/.planning/HANDOFF.json

{
  "version": "1.0",
  "timestamp": "2026-04-21T22:33:11.666Z",
  "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",
  "plan": 3,
  "task": 3,
  "total_tasks": 3,
  "status": "paused",
  "completed_tasks": [
    {
      "id": 1,
      "name": "Стабилизировать Matrix MVP runtime: numeric platform_chat_id mapping, staged attachments, clean vendored platform repos",
      "status": "done",
      "commit": "4524a6a"
    },
    {
      "id": 2,
      "name": "Перевести transport layer на thin adapter над pinned upstream AgentApi и обновить тесты/документацию",
      "status": "done",
      "commit": "0c2884c"
    },
    {
      "id": 3,
      "name": "Провести финальную локализацию streaming bug и зафиксировать platform-side diagnosis в подробном отчёте",
      "status": "done",
      "commit": "0c2884c"
    }
  ],
  "remaining_tasks": [
    {
      "id": 4,
      "name": "Передать платформенной команде финальный bug report и дождаться triage/fix proposal",
      "status": "not_started"
    },
    {
      "id": 5,
      "name": "После ответа платформы решить follow-up phase для surfaces hardening: tokens_used optional, bounded session cache, import/config cleanup, protocol contract tests",
      "status": "not_started"
    },
    {
      "id": 6,
      "name": "После platform fix повторно прогнать Matrix live smoke на text/tool/file/image сценариях",
      "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": "Считать текущее значение неизвестным; не городить локальные костыли"
    }
  ],
  "human_actions_pending": [
    {
      "action": "Отправить платформенной команде финальный отчёт docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md",
      "context": "Это основной артефакт с итоговым аудиторским выводом и raw evidence",
      "blocking": true
    },
    {
      "action": "Решить, оформлять ли отдельную follow-up phase в roadmap под production cleanup surfaces после platform triage",
      "context": "Сейчас реализация признана рабочей, но проблемной; часть hardening-задач осознанно отложена",
      "blocking": false
    }
  ],
  "decisions": [
    {
      "decision": "Не патчить vendored platform repos для рабочей реализации; все platform-side изменения использовались только как временная локальная диагностика и были откатаны",
      "rationale": "Нужна чистая граница ответственности между surfaces и платформой",
      "phase": "04"
    },
    {
      "decision": "Оставить transport layer максимально thin: AgentApiWrapper только строит клиента на chat_id, а stream semantics принадлежат upstream AgentApi",
      "rationale": "Так проще локализовать баги и не смешивать platform bugs с локальными workaround’ами",
      "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; дальнейшие локальные обходы только размоют диагностику",
      "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, а не ещё одна попытка локально чинить поток."
}