feat(04-01): finalize AgentApi migration

.planning/ROADMAP.md

@@ -58,9 +58,9 @@ Plans:
 **Plans:** 3 plans
 
 Plans:
-- [ ] 04-01-PLAN.md — Replace AgentSessionClient with AgentApi; update sdk/real.py, bot.py, broken tests
-- [ ] 04-02-PLAN.md — !save, !load, !reset, !context handlers; PrototypeStateStore extensions; numeric interception
-- [ ] 04-03-PLAN.md — Dockerfile + docker-compose.yml + .env.example update
+- [x] 04-01-PLAN.md — Replace AgentSessionClient with AgentApi; update sdk/real.py, bot.py, broken tests
+- [x] 04-02-PLAN.md — !save, !load, !reset, !context handlers; PrototypeStateStore extensions; numeric interception
+- [x] 04-03-PLAN.md — Dockerfile + docker-compose.yml + .env.example update
 
 ---
 

.planning/STATE.md

@@ -3,13 +3,13 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: — Production-ready surfaces
 status: Ready to execute
-last_updated: "2026-04-17T12:34:33.578Z"
+last_updated: "2026-04-17T16:10:00.000Z"
 progress:
   total_phases: 5
-  completed_phases: 1
+  completed_phases: 2
   total_plans: 12
-  completed_plans: 6
-  percent: 50
+  completed_plans: 9
+  percent: 75
 ---
 
 # State
@@ -19,13 +19,13 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-02)
 
 **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра
-**Current focus:** Phase 02 — SDK Integration (blocked on Lambda platform SDK readiness)
+**Current focus:** Phase 04 complete — Matrix MVP implementation ready for testing
 
 ## Current Phase
 
-**Phase 2** of 3: SDK Integration
+**Phase 4** implementation complete: Matrix MVP
 
-Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is available.
+Phase 4 is implemented. Next step is manual and automated testing of the Matrix MVP flow before deciding on follow-up work.
 
 ## Decisions
 
@@ -43,6 +43,9 @@ Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is av
 - [Phase 01]: Removed Matrix reaction conversion entirely and kept command callbacks limited to !yes/!no.
 - [Phase 01]: Kept !settings as a pure snapshot surface while preserving mutable subcommands outside the dashboard.
 - [Phase 01]: Seeded invite and dispatcher tests with explicit next_chat_index and room ids instead of treating C1 as Matrix transport identity.
+- [Phase 04]: Replaced AgentSessionClient with AgentApiWrapper and persistent agent connection lifecycle in Matrix runtime.
+- [Phase 04]: Added !save, !load, !reset, and !context commands with pending-state interception and local prototype session metadata.
+- [Phase 04]: Added Matrix-only Docker packaging for MVP deployment; platform services remain external to this compose setup.
 
 ## Blockers
 
@@ -54,6 +57,7 @@ Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is av
 
 - Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT)
 - Phase 4 added: Matrix MVP: shared agent context and context management command
+- New platform signal: upcoming proper `chat_id` support should enable file-level context separation and stronger context management in a future follow-up phase.
 
 ## Performance Metrics
 
@@ -65,8 +69,11 @@ Phase 1 is complete. Phase 2 remains blocked until the Lambda platform SDK is av
 | 01 | 04 | 3 min | 2 | 7 | 2026-04-02T20:03:38Z |
 | 01 | 05 | 2 min | 2 | 7 | 2026-04-03T09:28:47Z |
 | 01 | 06 | 4 min | 2 | 7 | 2026-04-03T09:35:39Z |
+| 04 | 01 | 1 session | 1 wave | 8 | 2026-04-17 |
+| 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 |
+| 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 |
 
 ## Session
 
-- Last session: 2026-04-03T09:35:39Z
-- Stopped at: Completed 01-06-PLAN.md
+- Last session: 2026-04-17T16:10:00Z
+- Stopped at: Phase 4 implementation complete, ready for testing

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-01-SUMMARY.md

@@ -0,0 +1,29 @@
+# 04-01 Summary
+
+## Outcome
+
+Replaced the Matrix real backend's custom `AgentSessionClient` path with a shared
+`AgentApiWrapper` over upstream `lambda_agent_api.AgentApi`.
+
+## Changes
+
+- Added `sdk/agent_api_wrapper.py` to capture `MsgEventEnd.tokens_used` without
+  modifying `external/`.
+- Rewrote `sdk/real.py` to use a shared `agent_api`, stream text chunks from
+  `AgentApi.send_message()`, and emit a final `MessageChunk` with
+  `last_tokens_used`.
+- Updated `adapter/matrix/bot.py` to construct `RealPlatformClient` with
+  `AgentApiWrapper`, keep `AGENT_WS_URL` unchanged, and manage
+  `agent_api.connect()` / `agent_api.close()` around `sync_forever()`.
+- Stubbed `sdk/agent_session.py` as a compatibility placeholder.
+- Updated Matrix/runtime tests away from `thread_key` and per-request websocket
+  assumptions.
+
+## Verification
+
+- `pytest tests/platform/test_real.py -q`
+- `pytest tests/adapter/matrix/test_dispatcher.py -q`
+- `pytest tests/core/test_integration.py -q`
+- `pytest tests/platform/test_agent_session.py -q`
+
+All listed commands passed locally.