wip: 02-prototype paused at task 4/4
This commit is contained in:
parent
9c73266ea5
commit
7507b2f252
2 changed files with 138 additions and 40 deletions
|
|
@ -1,71 +1,97 @@
|
|||
{
|
||||
"version": "1.0",
|
||||
"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",
|
||||
"plan": 3,
|
||||
"task": 1,
|
||||
"total_tasks": 2,
|
||||
"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,
|
||||
"status": "paused",
|
||||
"completed_tasks": [],
|
||||
"remaining_tasks": [
|
||||
"completed_tasks": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Add a dev-only Matrix reset CLI with explicit modes",
|
||||
"status": "not_started"
|
||||
"name": "Add Direct Agent Session Transport (sdk/agent_session.py)",
|
||||
"status": "done",
|
||||
"commit": "de20ff6"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"name": "Replace the README reset ritual with the new restart and reset workflow",
|
||||
"status": "not_started"
|
||||
}
|
||||
],
|
||||
"blockers": [
|
||||
{
|
||||
"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": "Use the direct `agent` WebSocket for a working prototype and keep control-plane concerns deferred behind a compatibility shim."
|
||||
"name": "Add Local Prototype State (sdk/prototype_state.py)",
|
||||
"status": "done",
|
||||
"commit": "2fad1aa"
|
||||
},
|
||||
{
|
||||
"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.",
|
||||
"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"
|
||||
}
|
||||
],
|
||||
"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": "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`."
|
||||
"workaround": "Push or reapply external/platform-agent commit 1dca2c1 in the platform-agent repo before broader handoff."
|
||||
}
|
||||
],
|
||||
"human_actions_pending": [
|
||||
{
|
||||
"action": "Decide whether the direct-agent Matrix prototype should live in this repo or in a separate repo.",
|
||||
"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": "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.",
|
||||
"blocking": false
|
||||
},
|
||||
{
|
||||
"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
|
||||
"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.",
|
||||
"blocking": false
|
||||
}
|
||||
],
|
||||
"decisions": [
|
||||
{
|
||||
"decision": "Do not use `master` as the prototype backend yet.",
|
||||
"rationale": "Live repo analysis shows only minimal HTTP endpoints, not the consumer-facing APIs required by surfaces.",
|
||||
"phase": "02"
|
||||
"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": "Use the direct `agent` WebSocket as the prototype response path.",
|
||||
"rationale": "It already exists and can be wrapped behind the current `PlatformClient` boundary with limited adapter impact.",
|
||||
"phase": "02"
|
||||
"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": "Keep Matrix adapter logic as stable as possible and absorb platform differences inside a new `sdk/real.py` implementation.",
|
||||
"rationale": "This preserves expandability for later platform versions and avoids coupling transport code to a temporary backend shape.",
|
||||
"phase": "02"
|
||||
"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": "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": "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"
|
||||
}
|
||||
],
|
||||
"uncommitted_files": [
|
||||
".planning/HANDOFF.json",
|
||||
".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md"
|
||||
".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"
|
||||
],
|
||||
"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": "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."
|
||||
"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."
|
||||
}
|
||||
|
|
|
|||
72
.planning/phases/02-prototype/.continue-here.md
Normal file
72
.planning/phases/02-prototype/.continue-here.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
phase: 02-prototype
|
||||
task: 4
|
||||
total_tasks: 4
|
||||
status: paused
|
||||
last_updated: 2026-04-07T23:54:30.473Z
|
||||
---
|
||||
|
||||
<current_state>
|
||||
The Matrix direct-agent prototype is implemented and manually proven working on branch `feat/matrix-direct-agent-prototype`. The current code path can log into Matrix, accept invites, provision the first Space/chat tree for a fresh user, and send live text messages to a patched local `platform-agent` over WebSocket. The immediate remaining engineering gap is not feature delivery but resilience: backend/provider failures can still bubble up as `PlatformError` and crash the Matrix bot process.
|
||||
</current_state>
|
||||
|
||||
<completed_work>
|
||||
|
||||
- Task 1: Added `sdk/agent_session.py` and transport tests for direct WebSocket messaging with collision-safe `thread_key` generation.
|
||||
- Task 2: Added `sdk/prototype_state.py` and tests for stable local user mapping, settings defaults, and mutation-safe settings copies.
|
||||
- Task 3: Added `sdk/real.py` as the `PlatformClient` implementation, fixed import-time dependency leakage, and aligned thread-key tests to the actual dispatcher contract.
|
||||
- Task 4: Wired Matrix runtime selection through `MATRIX_PLATFORM_BACKEND=real`, documented usage in `README.md`, and added dispatcher coverage for real backend selection.
|
||||
- Fixed repeat Matrix invites so the bot now `join()`s before the existing-user early return path.
|
||||
- Added Russian runbook doc `docs/matrix-direct-agent-prototype-ru.md` and pushed the branch.
|
||||
- Manually validated live bring-up using a local patched `external/platform-agent` on port 8000 plus the Matrix homeserver `https://matrix.lambda.coredump.ru`.
|
||||
</completed_work>
|
||||
|
||||
<remaining_work>
|
||||
|
||||
- Add graceful degradation for backend/provider failures so `PlatformError` does not crash the Matrix process.
|
||||
- Decide whether to upstream or separately push the required `external/platform-agent` patch (`1dca2c1`) that enables WebSocket `thread_id`.
|
||||
- Optionally clean up repeat-invite UX if Space/chat reprovisioning should ever happen for already-known users.
|
||||
- Optionally prepare a PR from `feat/matrix-direct-agent-prototype`.
|
||||
</remaining_work>
|
||||
|
||||
<decisions_made>
|
||||
|
||||
- Keep the prototype in this repo, not a separate Matrix-only repo.
|
||||
- Keep Matrix adapter logic intact and absorb backend differences inside `sdk/`.
|
||||
- Split the real backend into `AgentSessionClient` and `PrototypeStateStore` behind `RealPlatformClient`.
|
||||
- Patch only `platform-agent` for per-thread memory instead of changing both `agent` and `agent_api`.
|
||||
- Use a serialized collision-safe thread key because Matrix user IDs contain colons.
|
||||
- For repeat invites, join the room but do not recreate Space/chat state if the user is already provisioned locally.
|
||||
</decisions_made>
|
||||
|
||||
<blockers>
|
||||
- Technical: provider/backend errors still crash the Matrix bot instead of returning a user-facing failure reply.
|
||||
- External: the required `platform-agent` patch exists only in the local clone under `external/` and is not yet upstream.
|
||||
- Operational: credentials used during manual bring-up were exposed in-session and should be rotated.
|
||||
</blockers>
|
||||
|
||||
<context>
|
||||
The important mental model is stable. `platform/master` is still not the backend for surfaces, so the working prototype goes directly to `platform-agent` over `/agent_ws/`. The live setup that worked was:
|
||||
- `surfaces-bot` branch: `feat/matrix-direct-agent-prototype`
|
||||
- Matrix bot env: `MATRIX_PLATFORM_BACKEND=real`, `AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/`
|
||||
- patched local `external/platform-agent` with `thread_id` support
|
||||
- provider configured through OpenRouter using model `qwen/qwen3.5-122b-a10b`
|
||||
|
||||
Important files:
|
||||
- `sdk/agent_session.py`
|
||||
- `sdk/prototype_state.py`
|
||||
- `sdk/real.py`
|
||||
- `adapter/matrix/bot.py`
|
||||
- `adapter/matrix/handlers/auth.py`
|
||||
- `docs/matrix-direct-agent-prototype-ru.md`
|
||||
|
||||
Important local-only dependency:
|
||||
- `external/platform-agent` commit `1dca2c1` (`feat: support websocket thread ids`)
|
||||
|
||||
Likely running background process at pause time:
|
||||
- local `platform-agent` server on port 8000, PID 13499
|
||||
</context>
|
||||
|
||||
<next_action>
|
||||
Start with the failure path: catch `PlatformError` around Matrix message handling so a bad provider response becomes a normal reply like “backend unavailable, try again later” instead of killing the process. After that, either upstream `external/platform-agent` commit `1dca2c1` or document it as an explicit prerequisite in the platform repo.
|
||||
</next_action>
|
||||
Loading…
Add table
Add a link
Reference in a new issue