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

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md

@@ -3,83 +3,60 @@ 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
+last_updated: 2026-04-23T11:46:45.938Z
 ---
 
 <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`.
+Phase 04 кодово стабилизирована вокруг direct upstream `AgentApi` per request. Коммит `7d58dd1` уже запушен в `origin/feat/matrix-direct-agent-prototype`. Старый checkpoint в этом файле устарел: после обратной связи от платформы мы убрали extra wrapper из prod path, перестали переиспользовать один websocket между запросами и после этого missing-first-chunk симптом перестал воспроизводиться локально.
 </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`).
+- Весь ранее собранный Matrix MVP контекст остаётся валидным: numeric `platform_chat_id`, staged attachments, shared workspace, context commands и Docker packaging уже на месте.
+- Продовый runtime path переведён на direct upstream client через `sdk/upstream_agent_api.py`; локальный `sdk/agent_api_wrapper.py` удалён из runtime path.
+- `sdk/real.py` теперь на каждый `send_message` и `stream_message` создаёт новый `AgentApi`, делает `connect()`, читает stream и сразу `close()`.
+- `AGENT_BASE_URL` зафиксирован как основной runtime contract; `AGENT_WS_URL` оставлен только как backward-compat fallback в env wiring.
+- Добавлена регрессия на reuse-sensitive missing-first-chunk сценарий и обновлены runtime/integration tests; `uv run pytest tests -q` прошёл (`196 passed`), `ruff` на затронутых файлах clean.
+- Кодовый фикс закоммичен и запушен: `7d58dd1` (`fix: use direct agent api per request`).
+- В сессионных выводах зафиксирован новый архитектурный принцип для следующих surfaces: не строить свой transport layer, держать только thin integration/session boundary над upstream transport.
 </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
+- Перед следующим кодом выбрать направление:
+  - если продолжаем Matrix, прогнать live smoke в реальном окружении на text/tool/file flow и проверить отсутствие regressions на direct per-request path;
+  - если переходим к Telegram/Max-подобной работе, открыть новую phase/spec под prod surface architecture.
+- Привести `.planning/STATE.md` и roadmap в полностью каноничное состояние отдельным planning/cleanup шагом, если хотим закрепить этот checkpoint не только через handoff.
+- Не смешивать дальнейшую surface/runtime работу с отдельным локальным diff в `core/handlers/message.py`, пока это не станет явной задачей.
 </remaining_work>
 
 <decisions_made>
 
-- Больше не трогать vendored platform repos ради рабочей реализации.
-- Больше не добавлять локальные transport hacks, маскирующие streaming bug.
-- Считать текущий missing-first-chunk баг platform-side дефектом до опровержения raw evidence.
-- Оставить `tokens_used=0` как честное ограничение current upstream contract, не симулировать это значение локально.
+- Matrix prod path должен использовать прямой upstream `AgentApi`, а не surface-owned wrapper с кастомной stream semantics.
+- Fresh connection per request принят как дефолтный lifecycle для этой surface, потому что именно reuse websocket оказался чувствительной точкой для missing-first-chunk симптома.
+- `AGENT_BASE_URL` это честный runtime contract; ws URL normalization допустим только как backward-compat env fallback.
+- Для следующих surfaces надо думать терминами `integration boundary` и `runtime contract`, а не терминами "написать свой transport layer".
 </decisions_made>
 
 <blockers>
-- Platform-side streaming bug: после tool/file flow начало ответа может пропадать.
-- Duplicate `END` на стороне платформы.
-- Image path на больших вложениях падает с `data-uri > 10 MB` и `WS 1009`.
-- Без ответа платформенной команды дальнейший transport-layer surgery в `surfaces` не имеет инженерного смысла.
+- Подтверждённого локального Matrix blocker после `7d58dd1` больше нет; дальше это вопрос product direction и live validation, а не active transport-firefight.
+- В worktree остаётся посторонний локальный diff в `core/handlers/message.py`; не смешивать его с будущими surface/runtime изменениями без отдельной задачи.
 </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
+- upstream transport authoritative; `surfaces` владеет только lifecycle, serialization, attachment forwarding, error mapping и reconciliation.
+- Старый narrative "ждём platform triage перед любыми transport changes" больше не актуален; transport change уже сделан и дал положительный эффект.
+- Предыдущий handoff и текущий `STATE.md` были написаны до этого решения, поэтому их надо читать как исторический контекст, а не как последнюю истину.
+- Проверка на false completion ничего критичного не показала: grep задел только фразу "compatibility placeholder" в `04-01-SUMMARY.md`, а не реальный незаполненный summary.
+- Текущие локальные non-handoff diff: `.planning/STATE.md` и `core/handlers/message.py`.
 </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`, а не повторно "чинить" стрим локальными обходами.
+1. Открыть этот обновлённый handoff, а не опираться на старый checkpoint про platform triage.
+2. Выбрать трек: Matrix live smoke или новая prod-surface phase.
+3. Если снова полезем в runtime, не возвращать custom transport wrapper и persistent shared websocket без очень сильной причины и регрессионных тестов.
 </next_action>