# Lambda Lab 3.0 — Surfaces

Matrix-бот для взаимодействия пользователя с AI-агентом Lambda.

## Статус

Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff.

---

## Архитектура

```
surfaces-bot/
  core/                  — общее ядро, не зависит от транспорта
    protocol.py          — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
    handler.py           — EventDispatcher: IncomingEvent → OutgoingEvent
    store.py             — StateStore Protocol + InMemoryStore + SQLiteStore
    chat.py              — ChatManager
    auth.py              — AuthManager
    settings.py          — SettingsManager

  adapter/
    matrix/              — matrix-nio адаптер

  sdk/
    interface.py         — PlatformClient Protocol (контракт к SDK)
    real.py              — RealPlatformClient (через AgentApi)
    mock.py              — MockPlatformClient (заглушка для тестов)

  config/
    matrix-agents.yaml   — реестр агентов

  docs/                  — документация
```

Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md)

---

## Деплой

### Переменные окружения

```bash
cp .env.example .env
```

| Переменная | Обязательна | Описание |
|---|---|---|
| `MATRIX_HOMESERVER` | ✓ | URL Matrix-сервера |
| `MATRIX_USER_ID` | ✓ | `@bot:example.org` |
| `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) |
| `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна |
| `AGENT_BASE_URL` | ✓ | HTTP-URL агента, например `http://platform-agent:8000` |
| `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` |
| `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) |
| `SURFACES_SHARED_VOLUME` | | имя Docker volume (по умолчанию `surfaces-agents`) |

### Реестр агентов

`config/matrix-agents.yaml` — статический маппинг пользователей на агентов:

```yaml
user_agents:
  "@user0:matrix.lambda.coredump.ru": agent-0
  "@user1:matrix.lambda.coredump.ru": agent-1

agents:
  - id: agent-0
    label: "Agent 0"
  - id: agent-1
    label: "Agent 1"
```

Если `user_agents` не задан или пользователь не найден — используется первый агент из списка.

### Production (bot-only)

```bash
docker compose --env-file .env -f docker-compose.prod.yml up -d --build
```

Поднимает только `matrix-bot`. Монтирует shared volume в `/agents`. Требует внешний `AGENT_BASE_URL`.

### Fullstack E2E (bot + agent)

```bash
docker compose --env-file .env -f docker-compose.fullstack.yml up --build
```

Поднимает `matrix-bot` вместе с локальным `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте.

### Сброс состояния (локально)

```bash
rm -f lambda_matrix.db && rm -rf matrix_store
```

---

## Shared volume: передача файлов

```
Bot (/agents)                       Agent (/workspace)
  └── surfaces/matrix/{user}/{room}/inbox/file  ←── одно и то же хранилище
```

Бот пишет входящие файлы в `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` и передаёт агенту относительный путь. Исходящие файлы агент пишет в `/workspace/...`, бот читает из `/agents/...`.

---

## Онбординг пользователя

1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере
2. Бот создаёт private Space `Lambda — {display_name}` и комнату `Чат 1`
3. Дальнейшее общение — в рабочих комнатах, не в DM

**Требование:** незашифрованные комнаты. E2EE не поддержан.

---

## Команды Matrix

### Работающие

| Команда | Действие |
|---|---|
| *(любое сообщение)* | Диалог с агентом, стриминг ответа |
| `!new [название]` | Создать новый чат |
| `!chats` | Список активных чатов |
| `!rename <название>` | Переименовать текущую комнату |
| `!archive` | Архивировать чат |
| `!clear` | Сбросить контекст текущего чата |
| `!yes` / `!no` | Подтвердить / отменить действие агента |
| `!list` | Файлы в очереди вложений |
| `!remove <n>` / `!remove all` | Удалить вложение из очереди |
| `!help` | Справка |

### Не работают / заглушки

| Команда | Статус |
|---|---|
| `!save` / `!load` / `!context` | Нестабильны: зависят от агента, сессии теряются при рестарте |
| `!settings` и подкоманды | Заглушки MVP, требуют готового SDK платформы |

---

## Отправка файлов агенту

Matrix-клиент отправляет файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь.

```
[отправил файл]
!list
  1. report.pdf

прочитай и сделай summary   ← файл уйдёт агенту вместе с этим текстом
```

---

## Известные ограничения

| Проблема | Причина |
|---|---|
| История теряется при рестарте агента | `platform-agent` использует `MemorySaver` (in-memory) |
| E2EE | `python-olm` не собирается на macOS/ARM |

---

## Разработка

```bash
uv sync
pytest tests/ -v
pytest tests/adapter/matrix/ -v   # только Matrix
```

## Документация

| Файл | Содержание |
|---|---|
| [`docs/deploy-architecture.md`](docs/deploy-architecture.md) | **Читать первым.** Топология деплоя, volume-контракт, AgentApi, конфигурация |
| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Команды бота, UX, передача файлов |
| [`docs/known-limitations.md`](docs/known-limitations.md) | Известные ограничения и обходные пути |
| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Внутренний протокол событий (для расширения) |