surfaces/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-PLAN.md

---
phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
plan: 03
type: execute
wave: 2
depends_on:
  - 04-01-PLAN.md
files_modified:
  - Dockerfile
  - docker-compose.yml
  - .env.example
autonomous: true
requirements:
  - Dockerfile for Matrix bot
  - docker-compose.yml with matrix-bot service
  - .env.example updated with AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND

must_haves:
  truths:
    - "Dockerfile builds successfully with python:3.11-slim base"
    - "lambda_agent_api installed in container despite Python version constraint"
    - "PYTHONPATH=/app set so adapter/matrix/bot.py is runnable as module"
    - "docker-compose.yml defines matrix-bot service with env_file: .env"
    - ".env.example contains AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND=real"
    - "CMD runs python -m adapter.matrix.bot"
  artifacts:
    - path: "Dockerfile"
      provides: "Matrix bot container image"
      contains: "python:3.11-slim"
    - path: "docker-compose.yml"
      provides: "Service definition for matrix-bot"
      contains: "matrix-bot"
    - path: ".env.example"
      provides: "Updated env template"
      contains: "AGENT_BASE_URL"
  key_links:
    - from: "Dockerfile"
      to: "external/platform-agent_api"
      via: "COPY + pip install with --ignore-requires-python"
      pattern: "ignore-requires-python"
---

<objective>
Package the Matrix bot in a Docker container. Create Dockerfile using python:3.11-slim,
install lambda_agent_api from the local external/ directory (bypassing the Python 3.14
version constraint), and define a docker-compose.yml for running the matrix-bot service.
Update .env.example with new variables.

Purpose: Enable reproducible MVP deployment of the Matrix bot in a container alongside
the separately-run platform-agent.

Output: Dockerfile, docker-compose.yml, updated .env.example.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.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
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create Dockerfile and docker-compose.yml</name>

  <read_first>
    - .env.example (full file — adding new vars)
    - external/platform-agent_api/lambda_agent_api/ (ls — verify files to copy)
    - pyproject.toml (verify uv is the package manager used)
  </read_first>

  <files>Dockerfile, docker-compose.yml, .env.example</files>

  <action>
1. Check if pyproject.toml uses uv or pip. The project uses `uv sync` per CLAUDE.md. However, in the Docker container we can use pip for simplicity since uv's lockfile-based install may need the lockfile present. Use pip for the base install of surfaces-bot deps, and install lambda_agent_api separately.

   Actually: the project uses uv. Use uv in Docker to be consistent:
   - Install uv via pip (pip install uv)
   - Run uv sync to install project deps
   - Install lambda_agent_api with pip --ignore-requires-python

2. Create Dockerfile:

```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install uv
RUN pip install --no-cache-dir uv

# Copy dependency manifests first for layer caching
COPY pyproject.toml uv.lock* ./

# Install project dependencies via uv (no project install yet, just deps)
RUN uv sync --no-install-project --frozen 2>/dev/null || uv sync --no-install-project

# Copy project source
COPY . .

# Install the project itself
RUN uv sync --frozen 2>/dev/null || uv sync

# Install lambda_agent_api, bypassing Python version constraint
RUN pip install --no-cache-dir --ignore-requires-python /app/external/platform-agent_api

ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1

CMD ["python", "-m", "adapter.matrix.bot"]
```

3. Create docker-compose.yml:

```yaml
services:
  matrix-bot:
    build: .
    env_file: .env
    restart: unless-stopped
    # platform-agent runs separately — not included in this compose file
```

4. Read current .env.example, then append new variables. Current file likely has MATRIX_* vars. Add:
   - AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/
   - AGENT_BASE_URL=http://127.0.0.1:8000
   - MATRIX_PLATFORM_BACKEND=real

   Read .env.example first to see what's there, then write the full updated file.
  </action>

  <done>
    - `grep "python:3.11-slim" Dockerfile` returns a match
    - `grep "ignore-requires-python" Dockerfile` returns a match (lambda_agent_api install)
    - `grep "PYTHONPATH=/app" Dockerfile` returns a match
    - `grep "adapter.matrix.bot" Dockerfile` returns a match (CMD)
    - `grep "matrix-bot" docker-compose.yml` returns a match
    - `grep "env_file" docker-compose.yml` returns a match
    - `grep "AGENT_BASE_URL" .env.example` returns a match
    - `grep "MATRIX_PLATFORM_BACKEND" .env.example` returns a match
    - Dockerfile exists with python:3.11-slim, uv install, lambda_agent_api pip install --ignore-requires-python, PYTHONPATH=/app, CMD python -m adapter.matrix.bot
    - docker-compose.yml exists with matrix-bot service, env_file: .env, restart: unless-stopped
    - .env.example contains AGENT_WS_URL, AGENT_BASE_URL, MATRIX_PLATFORM_BACKEND=real
  </done>

  <verify>
    <automated>grep "python:3.11-slim" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile && grep "ignore-requires-python" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile && grep "AGENT_BASE_URL" /Users/a/MAI/sem2/lambda/surfaces-bot/.env.example && echo "All checks passed"</automated>
  </verify>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| container → host env | .env file mounts secrets into container |
| container → platform-agent | Network call to AGENT_WS_URL / AGENT_BASE_URL |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-04-03-01 | Information Disclosure | .env file with secrets mounted in container | mitigate | .env in .gitignore; .env.example committed with placeholder values only, never real secrets |
| T-04-03-02 | Tampering | lambda_agent_api installed from local path via --ignore-requires-python | accept | Local package under version control; no external supply chain risk |
| T-04-03-03 | Denial of Service | restart: unless-stopped could loop on crash | accept | Expected behavior; operator can `docker compose stop` |
</threat_model>

<verification>
```bash
# Verify files exist and contain expected content
grep "python:3.11-slim" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile
grep "ignore-requires-python" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile
grep "AGENT_BASE_URL" /Users/a/MAI/sem2/lambda/surfaces-bot/.env.example
grep "matrix-bot" /Users/a/MAI/sem2/lambda/surfaces-bot/docker-compose.yml
```
</verification>

<success_criteria>
- Dockerfile, docker-compose.yml, .env.example all exist in project root
- Dockerfile builds without errors when platform-agent_api dir is present (docker build . exits 0)
- .env.example contains AGENT_BASE_URL, AGENT_WS_URL, MATRIX_PLATFORM_BACKEND
- docker-compose.yml service named matrix-bot uses env_file: .env
</success_criteria>

<output>
After completion, create `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md`
</output>