Mikhail Putilovskij
6693d72cbd
- add 05-03 summary with task commits and verification details - update roadmap and state for completed Phase 05 plan 03
103 lines
4.8 KiB
Markdown
103 lines
4.8 KiB
Markdown
---
|
|
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*
|