diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e81178c..b27bdb1 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -64,6 +64,29 @@ Plans: --- +### Phase 05: MVP Deployment + +**Goal:** Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru без потери Space+rooms UX: закрепить per-room `platform_chat_id`, реальный `!clear`, reconciliation, file transfer через shared volume и разделение prod/fullstack compose. + +**Depends on:** Phase 4 + +**Plans:** 1/4 plans executed + +Plans: +- [ ] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync +- [ ] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics +- [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment +- [ ] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs + +**Deliverables:** +- Space+rooms onboarding remains the primary Matrix UX +- Per-room `platform_chat_id` provides true context isolation and `!clear` +- Reconciliation restores room metadata and routing after restart +- File transfer uses shared `/agents/` volume with room-safe behavior +- `docker-compose.prod.yml` is bot-only handoff; `docker-compose.fullstack.yml` is for internal E2E testing + +--- + ### Phase 3: Production Hardening **Goal:** Подготовить боты к реальному деплою — конфиг, логирование, мониторинг, обработка ошибок. diff --git a/.planning/STATE.md b/.planning/STATE.md index 5d87f69..5c8e4ce 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,14 +2,13 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Phase 04 complete — deployment architecture clarified, Phase 05 ready to plan -last_updated: "2026-04-27T18:44:51Z" +status: Executing Phase 05 +last_updated: "2026-04-27T22:06:43.419Z" progress: - total_phases: 5 + total_phases: 6 completed_phases: 2 - total_plans: 12 - completed_plans: 9 - percent: 75 + total_plans: 16 + completed_plans: 10 --- # State @@ -19,21 +18,18 @@ progress: See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра -**Current focus:** Phase 04 multi-agent routing follow-up fully implemented; ready for live validation or Phase 05 planning +**Current focus:** Phase 05 — mvp-deployment ## Current Phase -**Phase 4** implementation complete: Matrix MVP + multi-agent routing +**Phase 05** in progress: MVP deployment hardening -All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-direct-agent-prototype`: +Plan `05-03` is complete. Shared-volume attachment handling now keeps Matrix file references room-safe on disk and relative across the `/agents` deployment boundary. -- `7627012` / `242f4aa` / `9ccba16` — agent registry loader, RoutedPlatformClient facade, fail-fast on missing registry in real mode -- `a65227e` — dispatch chat_id contract alignment -- `74cf028` — `!agent` command, `selected_agent_id` persistence, unbound-room binding on first selection -- `7623039` — attachment normalization in core message handler -- `e733119` — stale room blocking, `agent_id` binding on `!new`, durable restart state tests +- `cafb0ec` — failing regressions for `/agents` workspace paths and send-file normalization +- `9a03160` — runtime normalization of `/workspace` and `/agents` absolute paths back to relative `workspace_path` values -135 Matrix tests pass. The branch is ready for review and merge. +Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. ## Decisions @@ -60,6 +56,9 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d - [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient). - [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata. - [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test. +- [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts. +- [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references. +- [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering. ## Blockers @@ -72,7 +71,7 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d - 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 - Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence) -- New platform signal: upcoming proper `chat_id` support should enable file-level context separation and stronger context management in a future follow-up phase. +- Phase 05 reset on 2026-04-28: erroneous single-chat deployment artifacts were removed before fresh planning. ## Performance Metrics @@ -88,9 +87,10 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d | 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 | | 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | | 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | +| 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | ## Session -- Last session: 2026-04-24T14:10:00Z -- Stopped at: Deployment architecture clarified with platform team; docs/deploy-architecture.md written; Phase 05 ready to plan -- Resume file: .planning/.continue-here.md +- Last session: 2026-04-27T22:06:43Z +- Stopped at: Completed 05-03-PLAN.md +- Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md new file mode 100644 index 0000000..0745e7c --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md @@ -0,0 +1,103 @@ +--- +phase: 05-mvp-deployment +plan: 03 +subsystem: infra +tags: [matrix, attachments, shared-volume, agents, pytest] +requires: + - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma + provides: direct AgentApi integration and Matrix outgoing file rendering +provides: + - shared-volume attachment path regressions for /agents deployment + - relative workspace-path normalization for upstream attachment transport + - send-file event normalization for Matrix outbound file rendering +affects: [matrix, deployment, shared-volume, file-transfer] +tech-stack: + added: [] + patterns: [relative workspace_path transport, shared-volume root normalization] +key-files: + created: [] + modified: + - tests/adapter/matrix/test_files.py + - tests/platform/test_real.py + - sdk/real.py +key-decisions: + - "Keep adapter/matrix/files.py as the only path-construction source; sdk/real.py only normalizes attachment references crossing the shared-volume boundary." + - "Normalize both /workspace and /agents absolute paths back to relative workspace paths before forwarding to the agent API or rendering Matrix send-file events." +patterns-established: + - "Matrix attachment transport stays relative even when the bot sees absolute shared-volume paths." + - "Agent-emitted file paths are rendered back to Matrix without HTTP proxy shims or inline blobs." +requirements-completed: [PH05-04] +duration: 3 min +completed: 2026-04-27 +--- + +# Phase 05 Plan 03: Shared-volume attachment path hardening Summary + +**Room-safe Matrix inbox paths and relative shared-volume attachment normalization for `/agents` deployment** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-04-27T22:02:34Z +- **Completed:** 2026-04-27T22:05:41Z +- **Tasks:** 2 +- **Files modified:** 3 + +## Accomplishments +- Added regression coverage for room-safe `surfaces/matrix/.../inbox/...` attachment layout under `/agents` workspaces. +- Added explicit tests for `/workspace/...` and `/agents/...` attachment-path normalization on both upstream send and downstream send-file rendering. +- Tightened `RealPlatformClient` so only relative `workspace_path` values are forwarded to the agent API. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add shared-volume file contract tests for `/agents` deployment** - `cafb0ec` (test) +2. **Task 2: Tighten attachment path handling for the shared volume contract** - `9a03160` (fix) + +## Files Created/Modified +- `tests/adapter/matrix/test_files.py` - covers room-safe shared-volume inbox paths under an `/agents` workspace root. +- `tests/platform/test_real.py` - covers relative attachment forwarding and send-file normalization for `/workspace` and `/agents` paths. +- `sdk/real.py` - normalizes shared-volume roots before attachments cross the upstream or Matrix rendering boundary. + +## Decisions Made +- Kept `adapter/matrix/files.py` unchanged so path construction remains centralized there. +- Reused one normalization helper in `sdk/real.py` for both `_attachment_paths()` and `_attachment_from_send_file_event()` to keep inbound and outbound behavior aligned. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Adjusted verification to use the project uv environment** +- **Found during:** Task 2 (Tighten attachment path handling for the shared volume contract) +- **Issue:** The plan's raw `pytest` command collected with an interpreter missing `PyYAML`, which blocked `tests/adapter/matrix/test_send_outgoing.py` before runtime assertions could execute. +- **Fix:** Re-ran verification with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest ...`, matching the repo's `CLAUDE.md` guidance and the project `.venv`. +- **Files modified:** None +- **Verification:** `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v` +- **Committed in:** None (verification-environment adjustment only) + +--- + +**Total deviations:** 1 auto-fixed (1 blocking) +**Impact on plan:** No scope creep. The deviation only changed the verification entrypoint so the planned test slice could run in the correct environment. + +## Issues Encountered +- The ambient `pytest` resolved to a different virtualenv than the project `.venv`, so direct verification was unreliable for dependency-backed Matrix tests. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Shared-volume file references now stay relative across inbound bot downloads, agent API attachment transport, and outbound Matrix send-file rendering. +- Phase 05 compose and deployment work can assume the `/agents` contract without adding file proxy infrastructure. + +## Self-Check: PASSED + +- Found `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md` +- Verified commit `cafb0ec` exists in git history +- Verified commit `9a03160` exists in git history + +--- +*Phase: 05-mvp-deployment* +*Completed: 2026-04-27*