wip: phase 4 planning complete, ready to execute
This commit is contained in:
parent
0e132849cc
commit
6923b801a3
7 changed files with 956 additions and 140 deletions
|
|
@ -1,97 +1,76 @@
|
|||
{
|
||||
"version": "1.0",
|
||||
"timestamp": "2026-04-07T23:54:30.473Z",
|
||||
"phase": "02-prototype",
|
||||
"phase_name": "matrix-direct-agent-prototype",
|
||||
"phase_dir": ".planning/phases/02-prototype",
|
||||
"plan": 1,
|
||||
"task": 4,
|
||||
"total_tasks": 4,
|
||||
"timestamp": "2026-04-17T12:34:43.144Z",
|
||||
"phase": "04",
|
||||
"phase_name": "Matrix MVP: shared agent context and context management commands",
|
||||
"phase_dir": ".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma",
|
||||
"plan": null,
|
||||
"task": null,
|
||||
"total_tasks": null,
|
||||
"status": "paused",
|
||||
"completed_tasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Add Direct Agent Session Transport (sdk/agent_session.py)",
|
||||
"status": "done",
|
||||
"commit": "de20ff6"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"name": "Add Local Prototype State (sdk/prototype_state.py)",
|
||||
"status": "done",
|
||||
"commit": "2fad1aa"
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"name": "Implement RealPlatformClient (sdk/real.py)",
|
||||
"status": "done",
|
||||
"commit": "9784ca6"
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"name": "Wire Matrix Runtime to Real Backend (adapter/matrix/bot.py)",
|
||||
"status": "done",
|
||||
"commit": "94bdb44"
|
||||
}
|
||||
{"id": 1, "name": "Phase 4 CONTEXT.md — design decisions from session", "status": "done"},
|
||||
{"id": 2, "name": "Phase 4 RESEARCH.md — AgentApi lifecycle, platform findings", "status": "done"},
|
||||
{"id": 3, "name": "Phase 4 planning — 3 PLAN.md files (planner + checker + revision)", "status": "done"}
|
||||
],
|
||||
"remaining_tasks": [],
|
||||
"blockers": [
|
||||
{
|
||||
"description": "Backend/provider errors can still escape as PlatformError and crash the Matrix surface instead of degrading into a user-facing reply.",
|
||||
"type": "technical",
|
||||
"workaround": "Catch PlatformError in the message path or dispatcher boundary and emit a normal OutgoingMessage while logging the root cause."
|
||||
},
|
||||
{
|
||||
"description": "The required thread_id patch lives only in the local external/platform-agent clone and is not yet upstreamed.",
|
||||
"type": "external",
|
||||
"workaround": "Push or reapply external/platform-agent commit 1dca2c1 in the platform-agent repo before broader handoff."
|
||||
}
|
||||
"remaining_tasks": [
|
||||
{"id": 4, "name": "Execute 04-01: Replace AgentSessionClient with AgentApi + AgentApiWrapper", "status": "not_started"},
|
||||
{"id": 5, "name": "Execute 04-02: !save/!load/!reset/!context commands + PrototypeStateStore extensions", "status": "not_started"},
|
||||
{"id": 6, "name": "Execute 04-03: Dockerfile + docker-compose.yml + .env.example", "status": "not_started"}
|
||||
],
|
||||
"blockers": [],
|
||||
"human_actions_pending": [
|
||||
{
|
||||
"action": "Push or upstream the local external/platform-agent patch that adds WebSocket thread_id support.",
|
||||
"context": "The Matrix prototype depends on external/platform-agent commit 1dca2c1, but that change is only in the local clone under external/ and is not part of surfaces.git.",
|
||||
"action": "Request platform team to add POST /reset endpoint to platform-agent",
|
||||
"context": "!reset needs POST {AGENT_BASE_URL}/reset to reinitialize AgentService singleton. Currently returns unavailable. ~3 lines on their side.",
|
||||
"blocking": false
|
||||
},
|
||||
{
|
||||
"action": "Rotate exposed credentials used during manual testing.",
|
||||
"context": "Matrix password, provider key, and Telegram token were pasted into the session during bring-up and should be considered compromised.",
|
||||
"action": "Rotate credentials used during manual testing",
|
||||
"context": "Matrix password and OpenRouter API key sk-or-v1-d27c07... were shared in chat session.",
|
||||
"blocking": false
|
||||
}
|
||||
],
|
||||
"decisions": [
|
||||
{
|
||||
"decision": "Keep the prototype in this repo on its own branch rather than creating a separate Matrix spike repo.",
|
||||
"rationale": "This reuses the existing Matrix adapter and tests and keeps the migration path to future surfaces inside the same SDK boundary.",
|
||||
"phase": "02-prototype"
|
||||
"decision": "Wrap AgentApi in AgentApiWrapper (sdk/agent_api_wrapper.py) to add last_tokens_used tracking",
|
||||
"rationale": "AgentApi.send_message() drops MsgEventEnd without yielding it. Wrapper subclasses AgentApi and overrides _listen() to capture tokens_used. Avoids modifying external/ platform package.",
|
||||
"phase": "04"
|
||||
},
|
||||
{
|
||||
"decision": "Use a split backend boundary: AgentSessionClient plus PrototypeStateStore behind RealPlatformClient.",
|
||||
"rationale": "This keeps Matrix logic stable while allowing later replacement of local state with a real control plane.",
|
||||
"phase": "02-prototype"
|
||||
"decision": "Remove build_thread_key and thread_id from WS URL entirely",
|
||||
"rationale": "platform-agent origin/main does not support thread_id query param. Architecture: one container = one chat = isolated context by design.",
|
||||
"phase": "04"
|
||||
},
|
||||
{
|
||||
"decision": "Patch only platform-agent for per-chat memory and keep agent_api unchanged.",
|
||||
"rationale": "Reading thread_id from the WebSocket query string minimizes rebase surface and avoids rewriting the message payload contract.",
|
||||
"phase": "02-prototype"
|
||||
"decision": "!reset calls POST /AGENT_BASE_URL/reset, returns unavailable message if 404",
|
||||
"rationale": "MemorySaver is in-memory — endpoint reinitializes singleton. Endpoint not yet in platform-agent origin/main.",
|
||||
"phase": "04"
|
||||
},
|
||||
{
|
||||
"decision": "Use collision-safe serialized thread keys rather than the raw spec example matrix:user:chat format.",
|
||||
"rationale": "Matrix IDs contain colons, so the raw concatenation could collide across distinct user/chat tuples.",
|
||||
"phase": "02-prototype"
|
||||
"decision": "!save/!load are agent-mediated via formatted text messages to the agent",
|
||||
"rationale": "Agent has write_file/read_file tools for /workspace/contexts/. No direct FS access from surfaces-bot to agent container.",
|
||||
"phase": "04"
|
||||
},
|
||||
{
|
||||
"decision": "Treat repeat Matrix invites as join-only if the user was already provisioned.",
|
||||
"rationale": "Provisioning is one-time per locally known user; repeat invites should not recreate Space/chat trees but must still join the room.",
|
||||
"phase": "02-prototype"
|
||||
"decision": "!load numeric selection intercepted in on_room_message before dispatcher.dispatch()",
|
||||
"rationale": "Numeric input arrives as IncomingMessage not IncomingCommand. Keeps dispatcher clean.",
|
||||
"phase": "04"
|
||||
}
|
||||
],
|
||||
"uncommitted_files": [
|
||||
".planning/STATE.md",
|
||||
".planning/HANDOFF.json",
|
||||
".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md",
|
||||
".planning/phases/02-prototype/.continue-here.md",
|
||||
"docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md"
|
||||
".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-CONTEXT.md",
|
||||
".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-RESEARCH.md",
|
||||
".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-01-PLAN.md",
|
||||
".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-PLAN.md",
|
||||
".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-PLAN.md",
|
||||
"adapter/matrix/bot.py",
|
||||
"sdk/agent_session.py",
|
||||
"tests/adapter/matrix/test_dispatcher.py",
|
||||
"tests/platform/test_agent_session.py"
|
||||
],
|
||||
"next_action": "Resume by implementing graceful degradation for backend/provider failures so Matrix surface errors do not crash the process, then decide whether to upstream external/platform-agent commit 1dca2c1 and create a PR from feat/matrix-direct-agent-prototype.",
|
||||
"context_notes": "The direct-agent Matrix prototype is working end-to-end on branch feat/matrix-direct-agent-prototype and was manually validated against a live Matrix homeserver plus a locally running patched external/platform-agent. surfaces.git branch contains transport, local state, RealPlatformClient, runtime wiring, invite fix, and Russian runbook docs. Manual bring-up uncovered three real-world issues that were resolved: homeserver TLS trust on macOS/Python, repeat invites returning before join(), and provider/model auth mismatches. There is still one quality gap: backend errors currently bubble up and can kill the bot process. A local OpenRouter-backed external/platform-agent process was last seen listening on port 8000 (PID 13499) during pause."
|
||||
"next_action": "Pull platform-agent origin/main (git -C external/platform-agent pull), then execute Phase 4: /gsd-execute-phase 4. Wave 1: 04-01 alone. Wave 2: 04-02 + 04-03 in parallel.",
|
||||
"context_notes": "Phase 4 planning complete and verified (1 checker revision round). Plans are ready to execute. Key gotcha: lambda_agent_api pyproject.toml says requires-python>=3.14 but runs on 3.11 — Dockerfile needs uv pip install --ignore-requires-python. platform-agent local clone is 11 commits behind origin/main — must pull before execution. Wave structure: 04-01 (Wave 1, alone) → 04-02 + 04-03 (Wave 2, parallel). All old thread_id/AgentSessionClient logic gets replaced — sdk/agent_session.py becomes mostly dead code or deleted."
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue