# Matrix — описание прототипа

## Концепция

Один бот, каждый чат — отдельная комната, все комнаты собраны в Space.

При первом входе бот создаёт для пользователя личное пространство (Space) —
это как папка в Element. Внутри Space бот создаёт комнату для каждого нового
чата с агентом. Пользователь видит аккуратную структуру: одно пространство,
внутри — список чатов. История хранится нативно в Matrix — это часть протокола,
ничего дополнительно делать не нужно.

Matrix выбран как внутренняя поверхность: команды лаборатории, тестировщики,
разработчики скиллов. Поэтому UX здесь — про удобство работы, а не онбординг.

---

## Аутентификация

### Флоу
1. Пользователь приглашает бота в личные сообщения или пишет в общей комнате
2. Бот проверяет `@user:matrix.org` — есть ли аккаунт на платформе
3. Если нет — бот отправляет одноразовый код или ссылку
4. Пользователь подтверждает, платформа возвращает токен
5. Бот сохраняет привязку `matrix_user_id → platform_user_id`

### В моке
- Любой пользователь проходит аутентификацию автоматически
- Бот отвечает: «Добро пожаловать, {display_name}. Создаю ваше пространство...»
- Демонстрирует флоу без реальной платформы

---

## Чаты через Space + комнаты (вариант Б)

### Структура
```
Space: «Lambda — {display_name}»
  ├── 📌 Настройки          ← специальная комната для команд управления
  ├── 💬 Чат 1              ← первый чат, создаётся автоматически
  ├── 💬 Чат 2
  └── 💬 Исследование рынка ← пользователь сам называет
```

### Создание Space
При первом входе бот:
1. Создаёт Space `Lambda — {display_name}`
2. Создаёт комнату `Настройки` (закреплена вверху)
3. Создаёт первую комнату-чат `Чат 1`
4. Приглашает пользователя во все комнаты
5. Пишет в `Чат 1` приветствие

### Управление чатами
Команды работают в любой комнате Space:

| Команда | Действие |
|---|---|
| `!new` | Создать новый чат (новую комнату в Space) |
| `!new Название` | Создать чат с именем |
| `!rename Название` | Переименовать текущую комнату |
| `!archive` | Вывести комнату из Space (не удалять) |
| `!chats` | Показать список чатов |

### Создание нового чата
1. Пользователь пишет `!new` или `!new Анализ конкурентов`
2. Бот создаёт новую комнату в Space
3. Приглашает пользователя
4. Пишет приветствие и создаёт сессию на платформе
5. Пользователь переходит в новую комнату — начинает диалог

### В моке
- Space и комнаты создаются реально через matrix-nio
- Сессии — через MockPlatformClient
- История хранится в Matrix нативно

---

## Основной диалог

### Флоу сообщения
1. Пользователь пишет текст в комнату-чат
2. Бот показывает typing (m.typing event)
3. Запрос уходит в платформу (MockPlatformClient)
4. Бот отвечает в той же комнате

### Вложения
- Файлы, изображения отправляются как Matrix media events
- Бот принимает `m.file`, `m.image`, `m.audio`
- Передаёт в платформу как `attachments` через `IncomingMessage`
- В моке: подтверждение получения + заглушка-ответ

### Реакции как действия
Matrix поддерживает реакции на сообщения (`m.reaction`).
Используем это для подтверждения действий агента:

```
Агент: Хочу отправить письмо на vasya@mail.ru
       Тема: «Отчёт за неделю»

       👍 — подтвердить   ❌ — отменить
```

Пользователь ставит реакцию — бот обрабатывает. Нативно и удобно.

### Треды для длинных задач
Если агент выполняет долгую задачу (deep research, генерация документа),
бот создаёт тред от своего первого ответа и пишет промежуточные статусы туда.
Основной чат не засоряется.

```
Бот: Начинаю исследование по теме «AI агенты 2025» [→ в треде]
  └── Ищу источники... (1/4)
  └── Анализирую статьи... (2/4)
  └── Формирую отчёт... (3/4)
  └── Готово. Отчёт: [...]
```

---

## Комната «Настройки»

Специальная комната для управления агентом. Закреплена вверху Space.
Команды работают только здесь — не мешают диалогу в чатах.

### Коннекторы
```
!connectors                    — показать список
!connect gmail                 — подключить Gmail (OAuth ссылка)
!connect github                — подключить GitHub
!connect calendar              — подключить Google Calendar
!connect notion                — подключить Notion
!disconnect gmail              — отключить
```

Статус:
```
Коннекторы:
  ✅ Gmail — подключён (user@gmail.com)
  ❌ GitHub — не подключён → !connect github
  ❌ Google Calendar — не подключён
  ❌ Notion — не подключён
```

В моке: OAuth ссылка-заглушка → «Подключено ✓»

### Скиллы
```
!skills                        — показать список
!skill on browser              — включить Browser Use
!skill off browser             — выключить
```

Статус:
```
Скиллы:
  ✅ web-search     — поиск в интернете
  ✅ fetch-url      — чтение веб-страниц
  ✅ email          — чтение почты (требует Gmail)
  ❌ browser        — управление браузером
  ❌ image-gen      — генерация изображений
  ❌ video-gen      — генерация видео
  ✅ files          — работа с файлами
  ❌ calendar       — календарь (требует Google Calendar)
```

В моке: состояние хранится локально.

### Личность агента
```
!soul                          — показать текущий SOUL.md
!soul name Лямбда              — задать имя агента
!soul style brief              — стиль: brief | friendly | formal
!soul priority «разбирать почту утром»  — приоритетная задача
!soul reset                    — сбросить к дефолту
```

В моке: SOUL.md генерируется и хранится локально, агент обращается по имени.

### Безопасность
```
!safety                        — показать настройки
!safety on email-send          — требовать подтверждение перед отправкой письма
!safety off calendar-create    — не спрашивать для создания событий
```

Статус:
```
Подтверждение требуется для:
  ✅ отправка письма
  ✅ удаление файлов
  ✅ публикация в соцсетях
  ❌ создание события в календаре
  ❌ поиск в интернете
```

### Подписка
```
!plan                          — показать текущий план
```

```
Подписка: Beta (бесплатно)
Токены этот месяц: 800 / 1000
━━━━━━━━░░ 80%
```

Заглушка, реализует другая команда.

### Статус и диагностика
```
!status                        — состояние агента и платформы
!sessions                      — список активных сессий
!whoami                        — текущий аккаунт платформы
```

```
Статус:
  Платформа: ✅ доступна
  Агент: ✅ активен (сессия #abc123)
  Аккаунт: user@lambda.lab
  Активных чатов: 3
```

---

## FSM состояния

```
[Invite] → AuthPending → AuthConfirmed
                              ↓
                         SpaceSetup → Idle (в комнате Настройки)
                                        ↓
                    [новая комната] → SessionCreated → Idle (в чате)
                                                          ↓
                                            ReceivingMessage → WaitingResponse → Idle
                                                          ↓
                                            WaitingReaction (confirm) → [✅/❌] → Idle
                                                          ↓
                                            LongTask → [тред со статусами] → Done → Idle
```

---

## Стек

- Python 3.11+
- matrix-nio (async) — Matrix клиент
- MockPlatformClient → `platform/interface.py`
- structlog для логирования
- SQLite для хранения `matrix_user_id → platform_user_id`, состояния скиллов, маппинга `chat_id → room_id`