surfaces/docs/matrix-prototype.md

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

Концепция

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

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

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

---

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

Флоу

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. Создаёт первую комнату-чат Чат 1
3. Передаёт invite=[matrix_user_id] прямо в room_create(...) для Space и комнаты
4. Привязывает chat_id ↔ room_id в локальном состоянии
5. Пишет приветствие в Чат 1

Управление чатами

Команды работают в зарегистрированных комнатах бота:

Команда	Действие
!new	Создать новый чат (новую комнату в Space)
!new Название	Создать чат с именем
!help	Показать шпаргалку по доступным командам
!rename Название	Переименовать текущую комнату
!archive	Архивировать чат и вывести бота из комнаты
!chats	Показать список чатов
!settings, !skills, !soul, !safety, !plan, !status, !whoami	Настройки и диагностика

Создание нового чата

1. Пользователь пишет !new или !new Анализ конкурентов
2. Бот создаёт новую комнату в Space
3. Сразу приглашает пользователя через room_create(..., invite=[user_id])
4. Регистрирует комнату в локальном состоянии и ChatManager
5. Пользователь переходит в новую комнату — начинает диалог

В моке

• Space и комнаты создаются реально через matrix-nio
• Сообщения передаются в MockPlatformClient с chat_id (C1, C2...)
• История хранится в Matrix нативно
• Дефолтные skills, safety, soul, plan подмешиваются даже после частичных локальных обновлений настроек

Переименование и архивирование

• !rename обновляет имя комнаты через state event m.room.name
• !archive архивирует чат в ChatManager и делает room_leave(...)
• Если бот потерял локальное состояние и видит комнату как unregistered:*, то !rename и !archive возвращают защитное сообщение вместо сломанного действия

---

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

Флоу сообщения

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)
  └── Готово. Отчёт: [...]

---

Настройки и диагностика

Отдельной комнаты Настройки в текущей версии нет. Команды вызываются как обычные !-команды из зарегистрированных комнат бота, а !settings отдаёт сводный dashboard по скиллам, личности, безопасности и активным чатам.

Коннекторы

!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                        — состояние платформы и чатов
!whoami                        — текущий аккаунт платформы

Статус:
  Платформа: ✅ доступна
  Аккаунт: user@lambda.lab
  Активных чатов: 3

---

FSM состояния

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

---

Стек

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

---

Ограничения текущей версии

• Ручной QA и текущая разработка идут только в незашифрованных комнатах
• После рестарта бот делает bootstrap sync и стартует с since, поэтому старые события не должны переигрываться повторно
• Если удалить локальную БД/стор, старые Matrix rooms останутся, но команды, завязанные на локальную регистрацию чатов, перестанут работать для этих комнат до повторного онбординга