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

12 KiB Raw Blame History Unescape Escape