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

context	phase	task	total_tasks	status	last_updated
phase	04-matrix-mvp-shared-agent-context-and-context-management-comma	null	null	ready_to_execute	2026-04-17T12:34:43.144Z

<current_state> Phase 4 planning is COMPLETE. 3 plans written, verified by checker, revised once. Ready to execute — no blockers.

Before executing: pull platform-agent origin/main: git -C external/platform-agent pull </current_state>

<completed_work>

• CONTEXT.md — all design decisions from 2026-04-16 session
• RESEARCH.md — AgentApi lifecycle, platform-agent origin/main state, store patterns
• 04-01-PLAN.md — Replace AgentSessionClient with AgentApiWrapper (Wave 1)
• 04-02-PLAN.md — !save/!load/!reset/!context commands (Wave 2)
• 04-03-PLAN.md — Dockerfile + docker-compose (Wave 2, parallel with 04-02)
• Checker passed after 1 revision (3 blockers fixed: tag rename, missing return, external/ modification) </completed_work>

<remaining_work>

• Execute Wave 1: 04-01 (AgentApi migration)
• Execute Wave 2: 04-02 + 04-03 in parallel </remaining_work>

<decisions_made>

• AgentApi wrapped in AgentApiWrapper (sdk/agent_api_wrapper.py) — subclasses AgentApi, overrides _listen() to capture MsgEventEnd.tokens_used. Do NOT modify external/platform-agent_api/
• build_thread_key and thread_id in WS URL removed entirely — architecture is one container = one chat
• !reset → POST {AGENT_BASE_URL}/reset; returns "unavailable" if 404 (endpoint not yet in platform-agent)
• !save/!load are agent-mediated: bot sends text message to agent, agent uses write_file/read_file in /workspace/contexts/
• !load numeric selection intercepted in on_room_message before dispatcher.dispatch()
• lambda_agent_api install needs --ignore-requires-python (pyproject.toml says >=3.14, runs fine on 3.11) </decisions_made>

None blocking execution.

Pending (non-blocking):

• POST /reset endpoint needs to be requested from platform team
• Credentials rotation (Matrix password, OpenRouter key sk-or-v1-d27c07...)

Required Reading (in order)

1. 04-CONTEXT.md — locked decisions
2. 04-RESEARCH.md — AgentApi interface details, platform-agent findings
3. external/platform-agent_api/lambda_agent_api/agent_api.py — AgentApi source (read before implementing wrapper)

Infrastructure State

• platform-agent local clone: 11 commits BEHIND origin/main — pull before executing
• surfaces-bot branch: feat/matrix-direct-agent-prototype
• platform-agent branch: main (local has our old thread_id patch on top)

Phase 4 is the main MVP delivery phase. The core insight: platform-agent uses thread_id="default" as a singleton by design — one container per chat, isolation at container level. We stop fighting this and embrace it. AgentSessionClient (our custom WS client) gets replaced by the platform team's AgentApi, wrapped to capture tokens_used. Four context management commands added: !save (agent writes summary to file), !load (agent reads file, user picks by number), !reset (POST /reset endpoint), !context (show session info).

<next_action>

1. git -C external/platform-agent pull (sync to origin/main)
2. /clear
3. /gsd-execute-phase 4 </next_action>