---
phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
task: 3
total_tasks: 3
status: paused
last_updated: 2026-04-21T22:33:11.666Z
---

<current_state>
Phase 04 как MVP-фаза по сути закрыта: Matrix real backend работает, transport layer очищен до thin adapter над pinned upstream `platform-agent_api.AgentApi`, ветка чистая и запушенная. Текущее состояние зафиксировано как "working but problematic": после tool/file flow остаётся подтверждённый upstream bug платформы, из-за которого начало ответа может пропадать.

Ключевой результат последней сессии: raw tracing показал, что первый повреждённый `MsgEventTextChunk` появляется уже внутри `platform-agent` до websocket-клиента. Это сняло основное подозрение с `surfaces`.
</current_state>

<completed_work>

- Переведён `sdk/agent_api_wrapper.py` в тонкий factory/shim без собственной stream-semantics.
- Переведён `sdk/real.py` на pinned upstream contract: без post-END drain, без custom listener, без локальной реконструкции стрима.
- Обновлены тесты под новый transport layer:
  - `tests/platform/test_real.py`
  - `tests/adapter/matrix/test_dispatcher.py`
  - `tests/core/test_integration.py`
- README обновлён под новое состояние интеграции и known limitations.
- Создан финальный отчёт: `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`.
- Временная диагностика в vendored `platform-agent` и `platform-agent_api` была использована только для расследования и полностью удалена; nested repos снова clean.
- Последний кодовый commit с рабочим состоянием: `0c2884c` (`refactor: use thin upstream transport adapter`).
</completed_work>

<remaining_work>

- Передать платформенной команде финальный отчёт и дождаться triage/fix proposal.
- После ответа платформы решить, открываем ли отдельную follow-up phase для production hardening в `surfaces`.
- После platform fix повторить live smoke:
  - text-only
  - staged attachments
  - tool/file flow
  - large image failure path
</remaining_work>

<decisions_made>

- Больше не трогать vendored platform repos ради рабочей реализации.
- Больше не добавлять локальные transport hacks, маскирующие streaming bug.
- Считать текущий missing-first-chunk баг platform-side дефектом до опровержения raw evidence.
- Оставить `tokens_used=0` как честное ограничение current upstream contract, не симулировать это значение локально.
</decisions_made>

<blockers>
- Platform-side streaming bug: после tool/file flow начало ответа может пропадать.
- Duplicate `END` на стороне платформы.
- Image path на больших вложениях падает с `data-uri > 10 MB` и `WS 1009`.
- Без ответа платформенной команды дальнейший transport-layer surgery в `surfaces` не имеет инженерного смысла.
</blockers>

<context>
Важная ментальная модель:

- `surfaces` сейчас максимально близок к upstream transport semantics.
- Если снова полезет corruption чанков, исходная презумпция должна быть "сначала смотреть platform-agent", а не придумывать новый локальный workaround.
- Главные артефакты для чтения перед продолжением:
  1. `README.md`
  2. `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`
  3. `sdk/agent_api_wrapper.py`
  4. `sdk/real.py`
  5. `tests/platform/test_real.py`

Если придётся продолжать без платформы, разумные задачи уже не про баг с чанками, а про clean/prod-ready улучшения вокруг него:

- сделать `tokens_used` optional в локальном контракте
- развести `RealPlatformClient` на pool/adapter слои
- добавить bounded session cache / idle eviction
- убрать `sys.path` import hack в пользу нормальной dependency wiring
- переименовать конфиг `AGENT_WS_URL` в более честный `AGENT_BASE_URL`
- добавить protocol contract tests против fake WS server
</context>

<next_action>
Start with:

1. Открыть `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`
2. Отправить этот отчёт платформенной команде как основной артефакт
3. Не менять transport layer до получения их ответа

Если работа продолжается автономно без ответа платформы, следующий допустимый шаг — оформлять отдельную follow-up phase на hardening `surfaces`, а не повторно "чинить" стрим локальными обходами.
</next_action>