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

phase	task	total_tasks	status	last_updated
04-matrix-mvp-shared-agent-context-and-context-management-comma	3	3	paused	2026-04-23T11:46:45.938Z

<current_state> 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>

• Весь ранее собранный 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>

• Перед следующим кодом выбрать направление:
  • если продолжаем 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>

• 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>

- Подтверждённого локального Matrix blocker после `7d58dd1` больше нет; дальше это вопрос product direction и live validation, а не active transport-firefight. - В worktree остаётся посторонний локальный diff в `core/handlers/message.py`; не смешивать его с будущими surface/runtime изменениями без отдельной задачи. Важная ментальная модель теперь такая:

• 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.

<next_action> Start with:

1. Открыть этот обновлённый handoff, а не опираться на старый checkpoint про platform triage.
2. Выбрать трек: Matrix live smoke или новая prod-surface phase.
3. Если снова полезем в runtime, не возвращать custom transport wrapper и persistent shared websocket без очень сильной причины и регрессионных тестов. </next_action>