# Требования к 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