145 lines
6.7 KiB
Markdown
145 lines
6.7 KiB
Markdown
---
|
|
phase: 05-mvp-deployment
|
|
plan: 03
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified:
|
|
- adapter/matrix/files.py
|
|
- sdk/real.py
|
|
- tests/adapter/matrix/test_files.py
|
|
- tests/platform/test_real.py
|
|
autonomous: true
|
|
requirements:
|
|
- PH05-04
|
|
must_haves:
|
|
truths:
|
|
- "Incoming Matrix attachments are written into a room-safe shared-volume path and passed upstream as relative workspace paths."
|
|
- "Agent-emitted files can be returned to Matrix users without inventing a separate file proxy."
|
|
- "The shared-volume contract works with the Phase 05 `/agents` deployment shape."
|
|
artifacts:
|
|
- path: "adapter/matrix/files.py"
|
|
provides: "Room-safe shared-volume path building and path resolution"
|
|
- path: "sdk/real.py"
|
|
provides: "Attachment path passthrough and send-file normalization"
|
|
- path: "tests/adapter/matrix/test_files.py"
|
|
provides: "Regression coverage for shared-volume path construction"
|
|
key_links:
|
|
- from: "adapter/matrix/files.py"
|
|
to: "sdk/real.py"
|
|
via: "relative `workspace_path` transport"
|
|
pattern: "workspace_path"
|
|
- from: "sdk/real.py"
|
|
to: "adapter/matrix/bot.py"
|
|
via: "OutgoingMessage attachments rendered back to Matrix"
|
|
pattern: "MsgEventSendFile"
|
|
---
|
|
|
|
<objective>
|
|
Harden the Matrix attachment path contract around the shared deployment volume instead of custom transport shims.
|
|
|
|
Purpose: Phase 05 file handling must survive real deployment with room-safe paths and outbound file delivery through the existing shared-volume model.
|
|
Output: Attachment-path regressions and any targeted runtime fixes needed for `/agents`-backed shared volume behavior.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@/Users/a/.codex/get-shit-done/workflows/execute-plan.md
|
|
@/Users/a/.codex/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
@.planning/phases/05-mvp-deployment/05-RESEARCH.md
|
|
@.planning/phases/05-mvp-deployment/05-VALIDATION.md
|
|
@docs/deploy-architecture.md
|
|
@docs/superpowers/specs/2026-04-20-matrix-shared-workspace-file-flow-design.md
|
|
@adapter/matrix/files.py
|
|
@sdk/real.py
|
|
@tests/adapter/matrix/test_files.py
|
|
@tests/platform/test_real.py
|
|
|
|
<interfaces>
|
|
From `adapter/matrix/files.py`:
|
|
|
|
```python
|
|
def build_workspace_attachment_path(
|
|
*,
|
|
workspace_root: Path,
|
|
matrix_user_id: str,
|
|
room_id: str,
|
|
filename: str,
|
|
timestamp: str | None = None,
|
|
) -> tuple[str, Path]: ...
|
|
```
|
|
|
|
From `sdk/real.py`:
|
|
|
|
```python
|
|
@staticmethod
|
|
def _attachment_paths(attachments: list[Attachment] | None) -> list[str]: ...
|
|
|
|
@staticmethod
|
|
def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment: ...
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 1: Add shared-volume file contract tests for `/agents` deployment</name>
|
|
<files>tests/adapter/matrix/test_files.py, tests/platform/test_real.py</files>
|
|
<read_first>tests/adapter/matrix/test_files.py, tests/platform/test_real.py, adapter/matrix/files.py, sdk/real.py, docs/deploy-architecture.md, .planning/phases/05-mvp-deployment/05-RESEARCH.md</read_first>
|
|
<behavior>
|
|
- Test 1: incoming Matrix files land under a room-safe `surfaces/matrix/.../inbox/...` path that remains relative to the agent workspace contract.
|
|
- Test 2: upstream file events normalize `/workspace/...` and `/agents/...`-style absolute paths into relative `workspace_path` values.
|
|
- Test 3: attachment forwarding never switches to inline blobs or HTTP shim URLs (per PH05-04).
|
|
</behavior>
|
|
<acceptance_criteria>
|
|
- `tests/adapter/matrix/test_files.py` asserts the path namespace includes sanitized user and room components.
|
|
- `tests/platform/test_real.py` contains explicit coverage for send-file path normalization.
|
|
- The automated test command in `<verify>` exercises both inbound and outbound sides of the shared-volume contract.
|
|
</acceptance_criteria>
|
|
<action>Expand the file-flow regressions around the real deployment contract described in research and `docs/deploy-architecture.md`. Keep the tests centered on relative `workspace_path` transport and room-safe on-disk layout. Do not introduce proxy URLs, base64 payload transport, or new platform endpoints.</action>
|
|
<verify>
|
|
<automated>pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v</automated>
|
|
</verify>
|
|
<done>Phase 05 has direct test coverage for `/agents`-backed shared-volume behavior across inbound and outbound file paths.</done>
|
|
</task>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 2: Tighten attachment path handling for the shared volume contract</name>
|
|
<files>adapter/matrix/files.py, sdk/real.py</files>
|
|
<read_first>adapter/matrix/files.py, sdk/real.py, tests/adapter/matrix/test_files.py, tests/platform/test_real.py, docs/deploy-architecture.md</read_first>
|
|
<behavior>
|
|
- Test 1: inbound attachment helpers keep returning relative paths even when the bot writes into `/agents`.
|
|
- Test 2: outbound file normalization accepts absolute paths from the agent runtime but strips them back to relative workspace paths for Matrix rendering.
|
|
- Test 3: no code path emits non-relative attachment references to the upstream agent API.
|
|
</behavior>
|
|
<acceptance_criteria>
|
|
- `sdk/real.py` only forwards relative attachment paths to the agent API.
|
|
- `sdk/real.py` normalizes both `/workspace` and `/agents` absolute roots if present in send-file events.
|
|
- `adapter/matrix/files.py` remains the single source of truth for room-safe attachment path construction.
|
|
</acceptance_criteria>
|
|
<action>Implement only the minimum runtime changes needed to satisfy the shared-volume tests. Keep `adapter/matrix/files.py` as the single place that builds surface-owned attachment paths, and keep `sdk/real.py` responsible only for attachment passthrough and send-file normalization. Do not widen this plan into compose edits, registry redesign, or bot command changes.</action>
|
|
<verify>
|
|
<automated>pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v</automated>
|
|
</verify>
|
|
<done>Incoming and outgoing file references stay compatible with the real shared-volume deployment contract, and the targeted file/path regressions pass.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
Run the Matrix file helper, real platform client, and outgoing-send slices together so the shared-volume contract is validated from write path through return-to-user rendering.
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
The Matrix bot and agent runtime can exchange file references through the shared volume using only relative workspace paths and room-safe storage layout.
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md`
|
|
</output>
|