surfaces/docs/reports/2026-04-01-surfaces-progress-report.md

Отчёт о проделанной работе

Проект: Lambda Lab 3.0 — Surfaces
Команда: Surfaces Team
Дата: 2026-04-01
Период отчёта: текущий этап разработки прототипов Telegram и Matrix

---

1. Цель этапа

Целью текущего этапа было собрать работоспособный прототип двух поверхностей для взаимодействия пользователя с AI-агентом Lambda:

• Telegram-бота
• Matrix-бота

При этом важным требованием было не ждать готовности платформенного SDK, а сразу строить систему вокруг собственного контракта и мок-реализации платформы. Это позволило параллельно двигаться по UX, архитектуре и интеграционным сценариям, не блокируясь внешними зависимостями.

---

2. Что было сделано на уровне архитектуры

2.1. Сформировано общее ядро

В репозитории выделено общее core/, которое не зависит от конкретного транспорта и используется обеими поверхностями.

Реализованы:

• единый протокол событий и ответов
• диспетчеризация входящих событий через EventDispatcher
• менеджмент чатов
• менеджмент аутентификации
• менеджмент настроек
• общее state-хранилище (InMemoryStore, SQLiteStore)

Это позволило построить Telegram и Matrix как тонкие адаптеры, которые:

• принимают события транспорта
• конвертируют их в единый формат ядра
• передают в core
• рендерят результат обратно в транспорт

2.2. Зафиксирован платформенный контракт

Вместо ожидания готового SDK был введён собственный контракт через:

• sdk/interface.py
• sdk/mock.py

За счёт этого:

• UX и интеграционный слой можно развивать уже сейчас
• реальные платформенные вызовы можно позже подключить заменой одной реализации
• транспортные адаптеры и core не придётся переписывать

2.3. Уточнена текущая архитектурная стратегия

По ходу работы часть исходных планов была пересмотрена и адаптирована под реальные ограничения платформ и API.

Ключевые изменения:

• platform/ был переименован в sdk/ для устранения конфликта имён и более точного смысла слоя
• Telegram ушёл от идеи автоматического создания групп ботом: Bot API этого не позволяет
• Matrix ушёл от Space-first реализации к DM-first / room-first модели как к более реалистичному первому рабочему этапу

---

3. Telegram: текущее состояние

3.1. Организация разработки

Telegram-часть выделена в отдельный worktree:

• ветка: feat/telegram-adapter

Это позволило вести Telegram независимо от Matrix и не смешивать контексты разработки.

3.2. Что реализовано

В Telegram-адаптере уже собран рабочий базовый UX:

• стартовый onboarding через /start
• основной диалог в DM
• создание новых чатов
• список чатов и переключение между ними
• меню настроек
• подтверждение действий через inline-кнопки
• базовая работа с вложениями

Отдельно реализован Forum Topics mode как расширение поверх DM-сценария:

• команда /forum
• подключение уже существующей forum-group через пересланное сообщение
• проверка, что бот является администратором с правом управления темами
• синхронизация существующих локальных чатов с forum topics
• routing сообщений из topic обратно в нужный chat context
• routing confirm callbacks внутри topic

3.3. Принятые продуктовые решения

Во время разработки были приняты важные решения по UX Telegram:

• основным пользовательским сценарием остаётся DM-first
• Forum Topics не являются обязательным режимом, а выступают как advanced mode
• контекст чатов должен синхронизироваться между DM и topic-представлением
• пользователь не должен сталкиваться с невозможной автоматизацией создания групп со стороны бота

3.4. Что ещё не закрыто

Для Telegram остаются открытые задачи, в первую очередь в области polish и согласованности UX:

• не все сценарии forum synchronization доведены до конца
• есть оставшиеся вопросы по командам в topic-контексте
• нужен дополнительный проход по UX-деталям и ручному QA

Актуальный follow-up зафиксирован в issue:

• #15 Telegram forum topics: remaining UX and synchronization gaps

---

4. Matrix: текущее состояние

4.1. Что реализовано

В main уже добавлен Matrix-адаптер, включающий:

• Matrix bot entrypoint
• converter layer
• room metadata store
• routing входящих событий
• обработку реакций
• обработку приглашения в DM
• базовый onboarding
• platform-aware command hints
• набор adapter-level тестов

4.2. Главный архитектурный сдвиг

Изначально Matrix рассматривался через модель:

• персональный Space
• settings-room
• отдельные room-чаты внутри Space

Однако по ходу реализации был выбран более прагматичный маршрут первого этапа:

• DM-first onboarding
• затем room-per-chat

Текущее поведение:

• пользователь приглашает бота в комнату
• бот приветствует пользователя
• первый контекст привязывается к C1
• команда !new создаёт реальную новую Matrix room
• бот приглашает пользователя в эту новую комнату

Это уже соответствует целевому принципу:

новый чат пользователя должен быть отдельной сущностью транспорта, а не только внутренней записью в core

4.3. Критические баги, которые были обнаружены и исправлены

Во время ручной проверки Matrix были найдены и устранены несколько важных проблем:

1. бот не принимал invite корректно

   • причина: подписка только на RoomMemberEvent
   • исправление: добавлена поддержка InviteMemberEvent

2. бот отвечал сам себе и уходил в цикл

   • симптом: спам приветствиями и сообщениями типа Введите !start
   • причина: отсутствие фильтра собственных сообщений
   • исправление: события от self.client.user_id теперь игнорируются

3. дублировалось стартовое приветствие

   • причина: invite-flow был неидемпотентным
   • исправление: room onboarding сделан идемпотентным

4. слишком агрессивные timeout/retry при sync

   • исправление: настроен более мягкий transport config через AsyncClientConfig

5. команды и подсказки были Telegram-ориентированными

   • исправление: тексты в ядре стали platform-aware (/start для Telegram, !start для Matrix)

4.4. Что подтверждено тестами

Для Matrix собран и пройден набор тестов:

• converter tests
• dispatcher tests
• reactions tests
• store tests
• интеграционные тесты core-сценариев

Примеры покрытых сценариев:

• разбор команд !new, !skills, !yes, !no
• invite onboarding
• защита от self-loop
• создание реальной Matrix room на !new
• mapping room_id -> chat_id

4.5. Ограничение текущей реализации

Главное незакрытое ограничение Matrix на текущий момент:

encrypted DM пока не поддержан

Причина не в логике бота, а во внешнем crypto-stack:

• для E2EE в matrix-nio нужен python-olm
• на текущей macOS/ARM среде сборка python-olm не воспроизводится корректно
• поэтому в рабочем сценарии Matrix пока используется только незашифрованный room flow

Это означает:

• незашифрованные комнаты и room-per-chat можно развивать и тестировать уже сейчас
• encrypted DM нужно рассматривать как отдельную инфраструктурную подзадачу

4.6. Что ещё остаётся по Matrix

Открытые направления:

• ручной QA текущего Matrix-бота
• доработка UX и edge-cases room-per-chat
• дальнейшее развитие settings-команд
• возможное возвращение к Space lifecycle как следующему этапу
• отдельный infrastructure task по E2EE / python-olm

Для ручного тестирования создан issue:

• #14 Manual QA: test Matrix bot and record issues / gaps

---

5. Что было сделано с точки зрения git и процесса

5.1. Основные изменения были оформлены коммитами

На текущем этапе были сделаны и запушены в репозиторий следующие ключевые коммиты:

• 82eb711 — базовый Matrix adapter + platform-aware command hints
• 14c091b — реальное создание новых Matrix rooms на !new
• 6a843e8 — transport timeout tuning для Matrix sync
• 27f3da8 — обновление README под фактическую архитектуру проекта

5.2. Проведён аудит backlog

По открытым issue был выполнен аудит:

• закрыты уже выполненные задачи
• устаревшие issue переписаны под текущую архитектуру
• не выполненные и актуальные задачи оставлены открытыми

В частности:

• закрыт issue #13 по Matrix research
• актуализированы старые Telegram и Matrix issue под текущие реальные пути, ограничения и UX-модель

---

6. Что изменилось по сравнению с изначальным планом

Это важный блок для руководителя: проект движется не просто по “чеклисту задач”, а по реальным ограничениям платформ.

6.1. Telegram

Изначально планировался сценарий, где бот создаёт Forum-группу сам.

Фактический результат исследования и реализации показал:

• Telegram Bot API этого не позволяет
• группа создаётся пользователем вручную
• бот подключается к уже существующей группе

Это не регресс, а корректная адаптация архитектуры под реальные ограничения API.

6.2. Matrix

Изначально планировался Space-first UX.

Фактически первым рабочим этапом стала модель:

• DM-first onboarding
• затем room-per-chat

Причина:

• так можно получить работающий transport flow раньше
• это проще в отладке
• это не блокирует дальнейший переход к Space lifecycle

6.3. Платформенный слой

Изначально существовали старые пути и слои, которые затем были пересобраны в более понятную форму.

Итоговое направление:

• sdk/interface.py
• sdk/mock.py
• core/ как единый уровень бизнес-логики
• transport adapters отдельно

Это повысило устойчивость архитектуры и упростило дальнейшую замену mock на реальный SDK.

---

7. Основные результаты этапа

К концу текущего этапа проект достиг следующих результатов:

Telegram

• есть рабочий Telegram adapter
• реализован основной DM flow
• реализован Forum Topics mode
• собрана отдельная ветка/worktree под Telegram
• основные пользовательские сценарии уже можно проверять руками

Matrix

• есть рабочий Matrix adapter
• invite/onboarding flow уже функционирует
• реализована модель room-per-chat
• устранены основные критические баги цикла и self-processing
• собран базовый test suite

Общий уровень проекта

• ядро и контракты унифицированы
• backlog приведён в соответствие с реальной архитектурой
• README актуализирован под текущее состояние
• ручной QA Matrix вынесен в отдельную управляемую задачу

---

8. Текущие риски и ограничения

Технические риски

1. Matrix E2EE

   • blocked внешним crypto-stack
   • не решается только правками Python-кода в проекте

2. Telegram forum synchronization

   • функциональность уже есть, но остаются edge-cases и UX-недоработки

3. Расхождение старых документов и новых решений

   • backlog уже частично синхронизирован
   • но часть старых design assumptions всё ещё может встречаться в документации

Процессные риски

1. требуется более строгий feature-branch workflow для следующих этапов Matrix
2. для Telegram и Matrix желательно продолжать раздельную работу по веткам/worktree
3. ручной QA остаётся критичным, особенно для Matrix transport behavior

---

9. Следующие шаги

Ближайшие

1. Провести ручной QA Matrix-бота по issue #14
2. Зафиксировать воспроизводимые проблемы Matrix
3. Продолжить Telegram в worktree feat/telegram-adapter
4. Довести Telegram forum synchronization gaps по issue #15

Среднесрочные

1. Расширить покрытие тестами
2. Довести Matrix settings workflow
3. Уточнить и обновить docs/api-contract.md
4. Отдельно решить вопрос Matrix E2EE support

Стратегические

1. Подготовить замену MockPlatformClient на реальный SDK
2. Довести обе поверхности до более стабильного demo-ready состояния
3. Выровнять UX Telegram и Matrix вокруг общих принципов surface protocol

---

10. Краткий вывод для руководителя

На текущем этапе команда не просто написала часть кода, а уже собрала работающий каркас двух поверхностей вокруг общего ядра и собственного платформенного контракта.

Главный практический результат:

• Telegram уже находится в стадии реального UX-прототипа
• Matrix уже имеет рабочий transport-слой и модель отдельных комнат для чатов
• архитектура проекта стала значительно устойчивее и ближе к реальной интеграции с платформой

При этом команда корректно адаптировала исходные планы под реальные ограничения Telegram Bot API и Matrix ecosystem, не пытаясь “продавить” заведомо неверные решения.

То есть проект движется не по формальному чеклисту, а по зрелой инженерной логике:

• исследование
• фиксация архитектурных решений
• рабочая реализация
• ручной QA
• корректировка backlog под фактическое состояние системы

Это хороший признак для дальнейшего перехода от прототипа к более устойчивой демонстрационной версии.

8. Дополнение: итоги отдельной Telegram-сессии по Forum Topics

В рамках отдельной рабочей сессии в Telegram worktree feat/telegram-adapter был проведён focused pass по качеству и устойчивости Forum Topics mode. Целью этой работы было не просто добавить функциональность, а довести forum-сценарии до состояния, в котором их можно стабильно демонстрировать, вручную тестировать и развивать дальше без постоянных расхождений между UX, кодом и документацией.

8.1. Что было выявлено в начале сессии

При аудите Telegram-ветки подтвердилось, что базовая реализация уже существует:

• Telegram adapter реализован
• Forum Topics mode уже добавлен
• /forum onboarding присутствует
• forum thread routing реализован
• confirm callbacks внутри forum thread уже работают

Однако вместе с этим были обнаружены существенные проблемы двух типов.

Первый тип — расхождение документации и фактической реализации. Часть документов всё ещё описывала старую DM-only или forum-only модель, тогда как код фактически уже работал как hybrid DM + Forum Topics.

Второй тип — реальные поведенческие баги forum mode. Наиболее заметные проблемы:

• нестабильный onboarding подключения forum group
• слабая диагностика ошибок подключения
• возможность сломать соответствие topic -> chat через команды управления чатами внутри topic
• неполная согласованность UX внутри forum topics

8.2. Исправление документации

Были актуализированы Telegram-документы, чтобы они соответствовали реальному состоянию ветки:

• docs/telegram-prototype.md
• docs/superpowers/specs/2026-03-31-telegram-adapter-design.md

Что было отражено в документации:

• Telegram работает как hybrid-модель DM + Forum Topics
• DM остаётся базовой поверхностью
• Forum Topics — расширенный режим поверх того же chat context
• /forum подключает уже существующую forum-group пользователя
• один и тот же chat_id может быть доступен как из DM, так и из forum topic
• forum thread routing и confirm callbacks уже входят в реализованную модель адаптера

Практический результат: документация перестала вводить в заблуждение разработчиков и reviewers и теперь описывает не гипотетическую, а фактическую архитектуру Telegram-ветки.

8.3. Разбор и исправление проблемного onboarding /forum

Изначально /forum опирался на пересланное сообщение из супергруппы и ожидал, что Telegram отдаст боту forward_from_chat.

В реальном запуске было установлено, что этот сценарий ненадёжен:

• Telegram/aiogram может присылать не forward_from_chat, а forward_origin
• в ряде случаев бот видит только forward_origin_type=user
• из такого payload невозможно надёжно восстановить group_id

То есть даже при визуально «правильной» пересылке сообщение не обязательно содержит необходимые данные о группе.

Для диагностики в onboarding были добавлены stage-level логи. Теперь логируются:

• запуск /forum
• получение onboarding message
• тип forward metadata
• наличие или отсутствие данных о группе
• тип найденного chat
• проверка forum-enabled supergroup
• права бота (administrator / can_manage_topics)
• успешная привязка forum group
• создание и привязка topics
• завершение onboarding

Это позволило быстро локализовать проблему и убедиться, что узкое место было именно в механике получения group_id.

8.4. Перевод onboarding на Telegram-native request_chat

Вместо ненадёжного forwarding-only flow основной путь подключения forum group был переведён на Telegram-native выбор чата через request_chat.

Было сделано следующее:

• добавлена новая клавиатура выбора forum-group
• /forum теперь предлагает пользователю выбрать подходящую group кнопкой
• бот получает chat_shared.chat_id напрямую
• после выбора выполняется проверка реальных прав бота в группе
• старый forwarding path оставлен как fallback

Это решение даёт несколько преимуществ:

• не зависит от нестабильных forwarded metadata
• даёт детерминированный chat_id
• лучше соответствует реальному Telegram API
• делает onboarding заметно понятнее для пользователя

8.5. Исправление ошибки USER_RIGHTS_MISSING

После внедрения request_chat на реальном запуске проявилась новая ошибка:

• TelegramBadRequest: USER_RIGHTS_MISSING

Ошибка возникала ещё на этапе отправки кнопки выбора forum-group.

Причина: в KeyboardButtonRequestChat был указан слишком жёсткий набор bot_administrator_rights, из-за чего Telegram отклонял сам запрос на показ кнопки.

Исправление:

• из request_chat были убраны жёсткие bot_administrator_rights
• фактическая проверка нужных прав оставлена на следующем шаге через get_chat_member

В результате onboarding сохранил строгую проверку прав, но перестал ломаться на этапе отправки UI.

8.6. Исправление опасного поведения внутри forum topics

После успешного onboarding был отдельно проверен UX внутри уже созданных topics. Здесь обнаружился критичный баг: пользователь мог использовать /chats в topic-контексте и переключать активный чат через inline callbacks.

Это приводило к рассинхронизации:

• Telegram topic визуально оставался темой одного чата
• FSM и routing переключались на другой чат
• пользователь начинал фактически разговаривать «в чате 4 внутри темы чата 2»

Чтобы устранить этот класс ошибок, были введены ограничения для topic-контекста.

Теперь внутри forum topic:

• /chats не открывает механизм переключения и сообщает, что эта функция доступна только в DM
• callback switch:<chat_id>:<name> запрещён
• callback new_chat из списка чатов запрещён

Это устранило основной сценарий, которым пользователь мог руками сломать привязку topic -> chat.

8.7. Что покрыто тестами

В рамках этой же сессии были расширены Telegram-specific тесты. Покрыты сценарии:

• forum routing helpers
• /forum переводит FSM в setup state
• подключение группы через forward_from_chat
• подключение группы через forward_origin
• подключение группы через chat_shared
• негативные сценарии без метаданных группы
• негативный сценарий для supergroup без Topics
• routing сообщений в forum thread
• создание forum topic при /new в DM
• регистрация чата в текущем topic
• confirm callback внутри forum thread
• запрет /chats внутри topic
• запрет switch callback внутри topic
• запрет new_chat callback внутри topic

Проверка выполнялась командами:

• pytest tests/adapter/telegram/test_forum.py -q
• pytest tests/core/test_dispatcher.py tests/core/test_integration.py -q

Результат: ключевые улучшения forum mode закреплены тестами, а не остались только на уровне ручной отладки.

8.8. Что ещё осталось как follow-up

Во время сессии были зафиксированы проблемы, которые разумно вынести в отдельную follow-up задачу, а не смешивать с текущими исправлениями.

Оставшиеся gap'ы:

• глобальные команды Telegram всё ещё видны и в topic-контексте, хотя часть из них логически там отключена
• /new <name> внутри уже связанного topic может переименовать локальный чат, но не переименовывает сам Telegram topic
• callback new_chat из DM-списка пока не синхронизирован с forum topic creation так же, как /new в DM

Эти пункты были вынесены в отдельный issue:

• #15 — Telegram forum topics: remaining UX and synchronization gaps

8.9. Git-результат Telegram-сессии

По итогам сессии изменения были оформлены отдельным коммитом и опубликованы в удалённую ветку.

Commit:

• a1b7a14 — Improve Telegram forum onboarding and topic safety

Push:

• origin/feat/telegram-adapter

8.10. Практический результат этой Telegram-сессии

На выходе Telegram Forum Topics mode стал существенно устойчивее и пригоднее для демонстрации и дальнейшей разработки.

Главные практические улучшения:

• forum onboarding стал надёжнее за счёт request_chat
• диагностика ошибок onboarding стала прозрачной
• пользователю стало сложнее случайно сломать topic-context
• документация приведена в соответствие с кодом
• изменения закреплены тестами
• остаточные проблемы не потеряны и вынесены в issue tracker

Итог: Telegram forum mode из состояния «уже работает, но легко ломается и плохо диагностируется» был переведён в состояние «работает заметно устойчивее, ограничивает опасные сценарии и имеет понятный backlog дальнейших улучшений».