[feat] add context and tasks for master-service

docs/master.md

@@ -0,0 +1,125 @@
+# Требования к master-service
+
+Источник: `meetings/meeting_1_document.md` + уточнение от тимлида
+
+## Назначение
+
+Master-service — это control plane платформы AI-агентов. Он управляет sandbox-контейнерами с AI-Agent, рабочими пространствами пользователей, чатами, пользовательскими файлами, проверкой доступа и выдачей временного p2p-доступа к контейнеру.
+
+После старта sandbox и успешной авторизации Master должен оставаться плоскостью управления, а не постоянным data-plane прокси: рабочий трафик к агенту должен идти напрямую по выданному p2p-каналу.
+
+## Границы ответственности
+
+### В scope
+
+- оркестрация sandbox
+- управление workspace и chat volume
+- хранение чатов? и файлов пользователя
+- хранение и выдача артефактов
+- проверка доступа
+- выдача и отзыв p2p-доступа
+- учет сессий, TTL и cleanup-процессов
+- хранение служебных метаданных
+
+### Вне scope
+
+- Telegram/Discord/Slack интеграции и их transport-логика
+- бизнес-логика AI-Agent внутри sandbox
+- реализация LLM-level защиты от prompt injection
+- реализация конкретных lambda-tools и browser tools
+
+## Основные сущности
+
+- **User** — владелец workspace
+- **Workspace** — пользовательское хранилище с мягкой квотой 10 GB
+- **Chat** — изолированная рабочая область внутри workspace
+- **SandboxSession** — активный runtime AI-Agent для конкретного чата
+- **AccessLease** — временное право на p2p-доступ к sandbox
+- **ChatFile** — файл, прикрепленный к чату
+- **Artifact** — результат, созданный агентом и подготовленный к выдаче наружу
+- **DependencyBundle** — предзагруженный набор зависимостей tool/runtime
+- **LambdaToolBundle** — платформенный read-only набор тулов
+
+## Функциональные требования
+
+### 1. Управление workspace и chat storage
+
+- **FR-001** Master должен создавать workspace пользователя при первом обращении
+- **FR-002** Master должен вести мягкую квоту workspace в 10 GB на пользователя без физического резервирования места
+- **FR-003** Master должен создавать, получать, перечислять и удалять чаты пользователя
+- **FR-004** Каждый chat должен иметь собственную изолированную директорию с файлами и историей
+- **FR-005** История сообщений чата в первой версии должна храниться рядом с чатом в файле `history.md`
+- **FR-006** Master должен сохранять пользовательские вложения в директорию соответствующего чата до запуска или во время работы sandbox
+- **FR-007** Master должен предоставлять операции списка, чтения метаданных, удаления и очистки файлов чата
+
+### 2. Оркестрация sandbox
+
+- **FR-008** Master должен поднимать sandbox-контейнер AI-Agent по первому сообщению или при отсутствии активной sandbox-сессии
+- **FR-009** Master должен переиспользовать активную sandbox-сессию, пока не истек TTL бездействия
+- **FR-010** Master должен завершать sandbox после периода неактивности; стартовое значение TTL — около 1 часа, но параметр должен быть конфигурируемым
+- **FR-011** После завершения sandbox данные чата и workspace должны сохраняться и использоваться при следующем старте
+- **FR-012** Master должен уметь пересоздать sandbox на другом узле при сохранности данных и доступности нужных volume
+
+### 3. Подключение volume и runtime-ресурсов
+
+- **FR-013** При старте sandbox Master должен подключать volume текущего чата
+- **FR-014** При старте sandbox Master должен подключать volume с dependency cache
+- **FR-015** При старте sandbox Master должен подключать volume с lambda-tools в режиме read-only
+- **FR-016** Если используются user-tools, Master должен подключать их так, чтобы агент мог их только исполнять, но не менять
+- **FR-017** Master должен проверять наличие нужных dependency bundle на текущем узле и при отсутствии инициировать загрузку из внутреннего хранилища
+
+### 4. Доступ и p2p-соединение
+
+- **FR-018** Master должен аутентифицировать внутренние запросы от интеграционного слоя и других доверенных сервисов
+- **FR-019** Master должен авторизовывать доступ по связке user/workspace/chat/sandbox
+- **FR-020** После успешной проверки доступа Master должен выдавать временные параметры p2p-подключения к sandbox
+- **FR-021** Выданный p2p-доступ должен быть ограничен по времени и привязан к конкретной sandbox-сессии
+- **FR-022** Master должен уметь отзывать p2p-доступ при остановке sandbox, смене прав или завершении сессии
+- **FR-023** Master не должен проксировать постоянный трафик к агенту после выдачи p2p-доступа, кроме управляющих операций
+
+### 5. Хранение чатов, файлов и артефактов
+
+- **FR-024** Master должен хранить центральные метаданные о пользователях, чатах, sandbox-сессиях, lease, файлах и артефактах
+- **FR-025** Master должен отделять метаданные чата в центральной БД от фактической истории сообщений в `history.db`
+- **FR-026** Master должен поддерживать загрузку артефактов в S3-совместимое объектное хранилище
+- **FR-027** Master должен хранить связь между артефактом, пользователем, чатом и способом внешней доставки
+- **FR-028** После подтвержденной отправки артефакт должен быть помечен на удаление или удален по policy
+
+### 6. Lifecycle и cleanup
+
+- **FR-029** Master должен отслеживать `last_read` и/или `last_update` для файлов чата
+- **FR-030** Файлы чата должны автоматически удаляться после 3 дней неактивности
+- **FR-031** Master должен поддерживать удаление всего workspace после длительной неактивности аккаунта; срок должен быть конфигурируемым
+- **FR-032** Cleanup должен быть безопасным: нельзя удалять данные активного sandbox или чата с действующим lease
+
+### 7. Наблюдаемость и аудит
+
+- **FR-033** Master должен логировать создание и остановку sandbox, подключение volume, выдачу доступа и cleanup-операции
+- **FR-034** Master должен собирать метрики по активным sandbox, времени запуска, ошибкам старта, cleanup и storage usage
+- **FR-035** Master должен предоставлять аудитный след по операциям доступа к chat/file/artifact ресурсам
+
+## Нефункциональные требования
+
+- **NFR-001** Master должен быть control-plane сервисом и не содержать бизнес-логику AI-Agent
+- **NFR-002** Все данные разных пользователей должны быть изолированы на уровне путей, mount policy и access policy
+- **NFR-003** Повторный запрос на создание chat или запуск sandbox не должен приводить к дублированию ресурсов при одинаковом идемпотентном ключе
+- **NFR-004** Политики TTL, cleanup, квоты и lease должны задаваться конфигом
+- **NFR-005** Решение должно позволять горизонтально масштабировать Master и пересоздавать sandbox независимо от конкретного инстанса сервиса
+- **NFR-006** Отказ sandbox не должен приводить к потере chat history и пользовательских файлов
+- **NFR-007** Все security-чувствительные операции должны быть трассируемы и наблюдаемы
+
+## Явные ограничения первой версии
+
+- один master-service отвечает за orchestration и storage metadata
+- история сообщений хранится в `history.md` внутри chat directory
+- workspace quota считается по фактическому размеру файлов, без hard reservation
+- heavy tools и browser automation не выносятся в отдельный сервис, пока это не потребуется
+- интеграции мессенджеров считаются внешними клиентами master-service
+
+## Открытые вопросы
+
+- какой именно transport используется для p2p-доступа: raw TCP, WebSocket, gRPC или другой вариант = WebSocket
+- какой срок inactivity cleanup для всего аккаунта считается продуктовым дефолтом
+- нужен ли отдельный API для скачивания chat files наружу или достаточно metadata + object/file gateway
+- подтверждается ли доставка артефакта внешней интеграцией явно или cleanup идет только по TTL
+- одна sandbox-сессия должна соответствовать одному chat или допустим multiplex нескольких чатов на один runtime