wip: matrix-restart-reconciliation-and-dev-reset-workflow paused at task 1/2

.planning/HANDOFF.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0",
-  "timestamp": "2026-04-04T10:13:58.720Z",
+  "timestamp": "2026-04-07T15:11:42.203Z",
   "phase": "01.1",
   "phase_name": "matrix-restart-reconciliation-and-dev-reset-workflow",
   "phase_dir": ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow",
@@ -23,65 +23,49 @@
   ],
   "blockers": [
     {
-      "description": "Phase 02 SDK integration remains blocked because platform control-plane contract is not stable yet; current platform repos only clearly expose the direct agent WebSocket layer.",
+      "description": "The longer-term Phase 02 platform integration is still blocked because `master` does not yet expose a stable user/chat/session/settings API for surfaces.",
       "type": "external",
-      "workaround": "Keep the current consumer-facing bot flows and mock-backed facade for now; use Matrix as the internal testing surface and revisit integration once master user/chat/session access is clarified."
+      "workaround": "Use the direct `agent` WebSocket for a working prototype and keep control-plane concerns deferred behind a compatibility shim."
+    },
+    {
+      "description": "The current `agent` implementation uses a shared fixed thread id, so all prototype conversations would share memory unless the agent side is parameterized by chat/session.",
+      "type": "external",
+      "workaround": "Ask the platform team for a minimal upstream change to accept per-chat thread identity, then keep the bot-side implementation inside `sdk/real.py`."
     }
   ],
   "human_actions_pending": [
     {
-      "action": "Confirm with the platform team the minimal control-plane contract for user/chat/session access and whether settings/attachments will exist in master.",
+      "action": "Decide whether the direct-agent Matrix prototype should live in this repo or in a separate repo.",
-      "context": "Current evidence shows agent_api is usable, but master is not yet a stable consumer-facing API.",
+      "context": "This determines whether the prototype is treated as a short-lived spike or the first durable real-backend path for surfaces.",
+      "blocking": true
+    },
+    {
+      "action": "Confirm with the platform team the minimal agent-side change needed to support per-chat or per-user thread identity.",
+      "context": "Without that, all conversations on the prototype would share a single memory thread.",
       "blocking": true
     }
   ],
   "decisions": [
     {
-      "decision": "Do not start a full rewrite of the consumer-facing bot integration yet.",
+      "decision": "Do not use `master` as the prototype backend yet.",
-      "rationale": "Platform direction is visible, but too many pieces outside the direct agent WebSocket protocol are still undefined or inconsistent.",
+      "rationale": "Live repo analysis shows only minimal HTTP endpoints, not the consumer-facing APIs required by surfaces.",
       "phase": "02"
     },
     {
-      "decision": "Treat sdk/mock.py as a temporary local integration facade rather than a near-drop-in replacement for the real platform.",
+      "decision": "Use the direct `agent` WebSocket as the prototype response path.",
-      "rationale": "The current mock assumes a unified platform API, while the real platform is split between control plane and direct agent session.",
+      "rationale": "It already exists and can be wrapped behind the current `PlatformClient` boundary with limited adapter impact.",
       "phase": "02"
     },
     {
-      "decision": "Use Matrix as the internal testing surface while waiting for the platform contract to stabilize.",
+      "decision": "Keep Matrix adapter logic as stable as possible and absorb platform differences inside a new `sdk/real.py` implementation.",
-      "rationale": "This preserves product iteration without coupling the bot too early to a moving platform backend.",
+      "rationale": "This preserves expandability for later platform versions and avoids coupling transport code to a temporary backend shape.",
       "phase": "02"
     }
   ],
   "uncommitted_files": [
-    ".planning/config.json",
+    ".planning/HANDOFF.json",
-    "adapter/matrix/bot.py",
+    ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md"
-    "adapter/matrix/handlers/__init__.py",
-    "adapter/matrix/handlers/auth.py",
-    "adapter/matrix/handlers/chat.py",
-    "adapter/matrix/handlers/settings.py",
-    "adapter/telegram/bot.py",
-    "sdk/mock.py",
-    "tests/adapter/matrix/test_chat_space.py",
-    "tests/adapter/matrix/test_dispatcher.py",
-    "tests/adapter/matrix/test_invite_space.py",
-    "tests/platform/test_mock.py",
-    ".planning/phases/01-matrix-qa-polish/01-01-SUMMARY.md",
-    ".planning/phases/01-matrix-qa-polish/01-04-SUMMARY.md",
-    ".planning/phases/01-matrix-qa-polish/01-05-PLAN.md",
-    ".planning/phases/01-matrix-qa-polish/01-06-PLAN.md",
-    ".planning/phases/01-matrix-qa-polish/01-VERIFICATION.md",
-    ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.gitkeep",
-    "bot-examples/",
-    "docs/reports/2026-04-01-surfaces-progress-report.md",
-    "docs/superpowers/plans/2026-03-31-matrix-adapter.md",
-    "docs/workflow-backup-2026-04-01.md",
-    "forum_topics_research.md",
-    "image copy 2.png",
-    "image copy.png",
-    "image.png",
-    "lambda_bot.db",
-    "lambda_matrix.db"
   ],
-  "next_action": "When resuming, either execute Phase 01.1 Plan 03 Task 1 (Matrix reset CLI) or continue the platform-integration design by defining a split MasterClient/AgentSession boundary without changing consumer adapters yet.",
+  "next_action": "On resume, either continue Phase 01.1 Plan 03 Task 1 (`adapter.matrix.reset`) or finish the design decision about whether the direct-agent prototype belongs in this repo or a separate repo.",
-  "context_notes": "This session was research-heavy rather than implementation-heavy. The key conclusion is that the real platform currently exposes a direct agent WebSocket SDK plus an unfinished master control plane; our mock models a richer unified platform than what exists today. That means future work should isolate the integration boundary, not rush a full rewrite."
+  "context_notes": "Latest conclusion as of 2026-04-07: full platform integration through `master` is still premature, but a usable Matrix prototype can be built now by introducing `sdk/real.py` as a compatibility shim over the direct `agent` WebSocket. The critical open design question is repo placement, followed by a small upstream request for per-chat thread identity in the agent."
 }

.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md

@@ -3,46 +3,52 @@ phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow
 task: 1
 total_tasks: 2
 status: paused
-last_updated: 2026-04-04T10:13:58.720Z
+last_updated: 2026-04-07T15:11:42.203Z
 ---
 
 <current_state>
-Formally, the most recently active GSD artifact is `01.1-03-PLAN.md`, which has not been executed yet. In parallel, an out-of-band research pass compared the local mock SDK against platform repos and concluded that Phase 02 SDK integration is still blocked on an unstable control-plane contract.
+Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`, which has not been implemented yet. Since the earlier checkpoint, a fresh live review of the platform repos confirmed that `master` still does not provide a usable consumer-facing control-plane API, but a working Matrix prototype is now feasible by talking directly to the `agent` WebSocket through a new `sdk/real.py` compatibility shim.
 </current_state>
 
 <completed_work>
 
-- Session research: inspected local `sdk/interface.py`, `sdk/mock.py`, core message/settings usage, and platform repos `agent_api`, `agent`, `master`, `docs`.
+- Re-analysed live platform repos on 2026-04-07 by cloning `platform/agent`, `platform/agent_api`, `platform/master`, and `platform/docs`.
-- Established that the real platform currently provides a direct WebSocket `agent_api` for talking to the agent, while `master` is still mostly a control-plane skeleton rather than a stable consumer-facing API.
+- Confirmed `master` is still only a thin HTTP skeleton with `/health` and `/users/{user_id}`, not a chat/session/settings backend for surfaces.
-- Confirmed that the current local mock assumes a richer unified platform API than what is actually implemented today.
+- Confirmed `agent` exposes a working `/agent_ws/` WebSocket and `agent_api` provides enough protocol/client code to stream model output.
-- Concluded that consumer adapters should not be deeply rewritten yet; Matrix remains the right internal testing surface for now.
+- Identified the real technical gap for a prototype: `agent` currently uses a singleton service with a fixed `thread_id="default"`, so all conversations would share memory unless that is parameterized.
+- Derived the recommended prototype path: keep Matrix adapter logic largely intact, add a new `sdk/real.py` shim for direct agent communication, and ask the platform team for a minimal agent-side change to support per-chat thread identity.
+- Started a product/architecture discussion about where that prototype should live: in this repo as the first real backend path, or in a separate repo as a Matrix-only spike. The user asked to save the session before answering that design question.
 </completed_work>
 
 <remaining_work>
 
 - Task 1: Implement `adapter.matrix.reset` with `local-only`, `server-leave-forget`, and `--dry-run`, plus tests.
 - Task 2: Update `README.md` so restart vs explicit reset workflow is documented and the old manual reset ritual is removed.
-- Phase 02 follow-up, once platform stabilizes: split the current platform boundary into control-plane and direct-agent-session abstractions instead of keeping a single `PlatformClient`.
+- Design follow-up: decide whether the direct-agent prototype belongs in this repo or a separate repo.
+- Future prototype work, once design is approved: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split.
 </remaining_work>
 
 <decisions_made>
 
-- Keep the current consumer-facing bot logic largely intact for now; do not force an early rewrite around the incomplete platform backend.
+- Do not integrate with `master` yet; it is still not the backend surfaces needs.
-- Treat `sdk/mock.py` as a temporary local integration facade, not as a near-drop-in simulation of the real platform.
+- Use the direct `agent` WebSocket as the only realistic path for a working prototype right now.
-- Use Matrix for internal testing while waiting for the platform team to finalize the minimal control-plane contract.
+- Keep consumer-facing Matrix logic as intact as possible and absorb backend differences inside a shim under `sdk/`.
+- Treat future platform evolution as likely to split into at least two concerns: control-plane access and direct agent session streaming.
 </decisions_made>
 
 <blockers>
-- Platform contract blocker: `agent_api` is concrete enough to study, but `master` still does not expose a stable user/chat/session/settings API for surfaces.
+- Phase 01.1 itself is not blocked; it is simply paused.
-- Product contract blocker: attachments, settings, webhook-style long task events, and exact session bootstrap flow are still unclear on the platform side.
+- Prototype blocker: the `agent` repo currently hardcodes a shared `thread_id`, so per-user/per-chat conversation isolation requires either a small upstream change or a careful workaround.
+- Platform contract blocker remains for the longer-term Phase 02 direction: `master` still lacks stable user/chat/session/settings APIs for surfaces.
 </blockers>
 
 <context>
-The key mental model from this session: our mock pretends the platform is already a complete backend, but the real platform today is split. There is a usable direct agent WebSocket protocol, and there is a developing master control plane, but they have not converged into the unified SDK shape that the bot currently assumes. Because of that, the right near-term move is not to rush integration, but to preserve momentum with Matrix/internal testing and keep the future integration boundary explicit.
+The important mental model changed slightly since the earlier checkpoint. Before, the conclusion was mainly “Phase 02 is blocked because the platform contract is unstable.” That is still true for full SDK integration through `master`, but it is no longer the whole story. There is now a practical bridge strategy: use the existing `agent` WebSocket directly for message generation, keep settings/user mapping local for the prototype, and preserve adapter stability by hiding all of this behind a new `sdk/real.py` implementation. The open architecture decision is repo placement: short-lived prototype repo versus building the first durable real-backend path here.
 </context>
 
 <next_action>
-Start with one of these, depending on priority:
+Resume with one of these depending on priority:
-1. Execute `01.1-03-PLAN.md` Task 1 and build the Matrix reset CLI.
+1. If continuing phase execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
-2. If returning to platform research, write a concrete draft interface for `MasterClient` + `AgentSession` while leaving consumer adapters unchanged.
+2. If continuing platform design, answer the pending repo-placement question: keep the prototype in this repo or create a separate repo for a Matrix-only spike.
+3. After that decision, write the design for the direct-agent shim path before touching code.
 </next_action>