surfaces/docs/matrix-prototype.md

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