[feat] add context and tasks for master-service
This commit is contained in:
Azamat
parent
c5d5e243c1
commit
f0c4988b44
3 changed files with 602 additions and 98 deletions
125
docs/master.md
Normal file
125
docs/master.md
Normal file
|
|
@ -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
|
||||
405
meetings/meeting_1_document.md
Normal file
405
meetings/meeting_1_document.md
Normal file
|
|
@ -0,0 +1,405 @@
|
|||
# Meeting 1 — Platform Architecture Design
|
||||
**Date:** 2026-03-21 (estimated from transcript context)
|
||||
**Duration:** ~1:30:18 (00:00 - 1:30:18)
|
||||
**Participants:** Azamat N (lead architect, screen-sharing), Egor (Егор), Yaroslav (Ярослав), David Shvarts (Давид Шварц), Andrey Bakhtiozin (Бахтиозин Андрей)
|
||||
**Platform:** DION video conferencing
|
||||
**Collaborative tool:** Excalidraw (shared whiteboard)
|
||||
|
||||
## Summary
|
||||
|
||||
The Lambda Lab 3.0 team held their first architecture planning meeting to design the AI-agent platform. Azamat presented a draft architecture he had developed with Egor over the preceding two days, walking through the system on a shared Excalidraw whiteboard. The platform consists of two main applications: a **Master** service (orchestrator managing sessions, containers, and context) and an **AI-Agent** service (running inside isolated Docker containers with a per-user workspace). The team discussed the workspace structure (10GB per user with chat-scoped files and history), three categories of tools (built-in, lambda/platform, and user-generated), dependency management via mount points, artifact storage via S3, and message history storage options. Key side topics included security concerns around prompt injection and file leakage, the agent-browser tool for web interaction, infrastructure decisions (Forgejo for Git hosting, Matrix for team communication), and upcoming deadlines — specifically presenting this architecture to Kalinin the next day.
|
||||
|
||||
The architecture is explicitly described as a first draft created in two days, meant to establish a direction rather than be final. The team assigned responsibilities: Azamat handles Forgejo repository setup, wiki documentation, and architecture presentation preparation. The meeting also touched on developer tooling — using Claude/OpenCode with agent profiles, CLAUDE.md-style configuration files, and CI/CD pipelines for documentation.
|
||||
|
||||
## Discussion
|
||||
|
||||
### Setup and Technical Issues
|
||||
**[00:00 — 02:14]**
|
||||
|
||||
The meeting opened with participants joining the DION video call and resolving recording/connection issues. Azamat briefly disconnected and reconnected. Five participants were present: Azamat N, Egor, Yaroslav, David Shvarts, and Andrey Bakhtiozin.
|
||||
|
||||
**Visual context:** DION video conferencing interface showing participant tiles with initials and names.
|
||||
|
||||
---
|
||||
|
||||
### Platform Architecture Overview
|
||||
**[02:17 — 04:50]**
|
||||
|
||||
Azamat shared his Excalidraw screen and began presenting the architecture he had drafted with Egor. He explained the overall platform goal: creating AI agents accessible through various integrations (Telegram, Discord, Slack), where the agent lives in an isolated environment.
|
||||
|
||||
The architecture has two main applications:
|
||||
|
||||
1. **Master** — orchestrator that manages agent sessions. When a user writes in Telegram, the message hits the Master, which creates a session and asks Docker to spin up a container with the AI-Agent.
|
||||
|
||||
2. **AI-Agent** — the second application, living inside an isolated Docker container. Once the container is running, communication happens directly between the messaging integration and the agent container (peer-to-peer), bypassing the Master.
|
||||
|
||||
> **Azamat** @ 02:37: "Вот наша задача сделать разными схемами платформу, которые подключаются к различной интеграции по типу Telegram, Discord и всего такого."
|
||||
|
||||
> **Azamat** @ 02:51: "Наша задача именно сделать агента, который живет в изолированной среде."
|
||||
|
||||
**Visual context:** Excalidraw diagram showing Stream (Telegram, Discord, Slack) -> Docker (multiple AI-Agent instances) -> Master (S3, DB). Arrows indicate data flow between components.
|
||||
|
||||
---
|
||||
|
||||
### Workspace Structure and Projects
|
||||
**[05:15 — 07:28]**
|
||||
|
||||
Azamat described the workspace allocated per user — 10GB of storage. Within this workspace, users can create projects (later renamed to "chats"), each containing files the agent interacts with (PDFs, images, documents, videos). This is analogous to ChatGPT's project feature.
|
||||
|
||||
> **Azamat** @ 05:15: "Мы ему выделяем 10 гигабайт памяти. Просто. И он в эти 10 гигабайт может делать, что хочет."
|
||||
|
||||
> **Azamat** @ 07:14: "У юзера, вот как в chat.gpt можно создавать проекты, здесь будет то же самое."
|
||||
|
||||
**Visual context:** Excalidraw diagram showing "Workspace 10GB" containing P1 (file1.pdf, file2.png), P2 (file3.docx), P3 (video.mp4).
|
||||
|
||||
---
|
||||
|
||||
### Tool Categories
|
||||
**[07:30 — 12:35]**
|
||||
|
||||
The team established three categories of tools:
|
||||
|
||||
**1. Built-in tools** (embedded in agent code):
|
||||
- `web-search` — web search capability
|
||||
- `fetch-url` — fetch a web page (e.g., `http://simple-file.ru/index.html`)
|
||||
- `bash` — command-line interaction (cd, ls, git, python, etc.)
|
||||
|
||||
**2. Lambda tools (platform-wide, read-only):**
|
||||
- Written by other teams within the organization
|
||||
- Example: `markitdown` — converts various formats (PDF, DOCX, HTML) to Markdown
|
||||
- Must support `--help`, `--json`/`--agent` flags for agent-friendly interaction
|
||||
- Must support `man-agent <tool>` for machine-readable documentation
|
||||
- Read-only, mounted into every agent container
|
||||
|
||||
**3. User tools (per-user, execute-only):**
|
||||
- Agent can write scripts to solve specific user tasks
|
||||
- Example: a simple task-tracker with `add` and `close` commands, backed by sqlite.db
|
||||
- Execute-only permissions (`+x only`) for security
|
||||
|
||||
> **Azamat** @ 10:38: "Когда мы вызываем условно какой-нибудь такой тул, у нас должно быть типа help и желательно еще минус-минус JSON, чтобы вот это агент понимал."
|
||||
|
||||
**Visual context:** Excalidraw showing AI-Agent sandbox with built-in tools listed, "Сторонние тулы RO" (third-party tools read-only) section, and "User-tool +x only" section. Workspace with P1/P2/P3 projects below.
|
||||
|
||||
---
|
||||
|
||||
### Security Discussion: User Tools
|
||||
**[15:58 — 16:30]**
|
||||
|
||||
Egor raised a security concern: if user tools are writable by the agent, a malicious prompt injection could cause the agent to modify user tools, inject code like `print(token)`, and exfiltrate credentials stored in environment variables.
|
||||
|
||||
> **Egor** @ 15:58: "Потому что это поможет подцепить где-нибудь вирусный промпт, полезть в папку UserTools, ввести туда какой-нибудь принт токен и слить токены оттуда."
|
||||
|
||||
The team agreed that user tools should have execute-only permissions and that this area needs further discussion.
|
||||
|
||||
---
|
||||
|
||||
### Dependency Management and Mount Points
|
||||
**[17:37 — 23:47]**
|
||||
|
||||
The team discussed how dependencies for tools (Python libraries, etc.) would be managed. Since downloading gigabytes of dependencies on every container launch is impractical, they decided to:
|
||||
|
||||
- **Pre-mount dependencies** on the host machine
|
||||
- Check if dependencies exist on the current node at container launch
|
||||
- If not present, download from their own S3/cloud storage (in the same data center) rather than external sources
|
||||
- Store as mounted volumes, not inside containers
|
||||
|
||||
Mount points defined:
|
||||
- `Mount cur-chat` — current chat/project files
|
||||
- `Mount dependencies` — pre-cached tool dependencies
|
||||
- `Mount lambda-tools` — shared platform tools (RO)
|
||||
|
||||
> **Azamat** @ 18:15: "Нам надо где-то сохранять, потому что на каждый запуск еще тянуть гигабайт со скоростью 100 килобит в секунду не очень хочется."
|
||||
|
||||
**Visual context:** Updated Excalidraw diagram showing mount points connected to the AI-Agent workspace, with arrows from host machine storage to container mounts.
|
||||
|
||||
---
|
||||
|
||||
### S3 Storage for Artifacts
|
||||
**[16:46 — 17:36]**
|
||||
|
||||
S3 is used for artifact storage — files the agent generates (reports, presentations, images) that need to be sent back to users via Telegram or other messengers. The agent uploads artifacts to S3, and they are delivered to the user through the messaging integration.
|
||||
|
||||
> **Azamat** @ 21:32: "Просто файл-помойка. Типа, если ты хочешь знать, как с ним работать, ты файлик просто по http туда загружаешь."
|
||||
|
||||
> **David** @ 22:08: "Считай просто это как Google диск, только наш."
|
||||
|
||||
---
|
||||
|
||||
### Projects vs. Chats Naming
|
||||
**[36:07 — 37:50]**
|
||||
|
||||
Confusion arose around the "project" naming because in ChatGPT, a project contains multiple chats. The team decided to rename "projects" to **"chats"** (C1, C2, C3) to avoid confusion. Each chat has its own files and history.db. The question of supporting multiple chats per project was deferred.
|
||||
|
||||
> **Azamat** @ 36:29: "Знаешь, короче, как чаты просто в GPT-шке, только мы их называли проектами."
|
||||
|
||||
> **Egor** @ 37:30: "Confusing naming тут."
|
||||
|
||||
---
|
||||
|
||||
### Message History Storage
|
||||
**[30:55 — 35:32]**
|
||||
|
||||
The team debated where to store message history. Options discussed:
|
||||
|
||||
1. **Central database** — rejected because querying by project_id across scattered chunks is inefficient
|
||||
2. **Per-chat file** (history.db) inside the workspace — accepted as the initial approach
|
||||
|
||||
Egor argued that per-chat SQLite files are more efficient since you always need the full history for a chat, not individual messages. The database fields discussed: `project_id`, `timestamp`, `msg`.
|
||||
|
||||
> **Egor** @ 34:45: "Каждый запрос в BD, ему нужно пройтись по индексу, найти все записи вот с этим project id, а они раскиданы все по разным чанкам."
|
||||
|
||||
> **Azamat** @ 36:04: "Я вспомнил про файлы типа memory.md, soul.md. Кто-то же так делает."
|
||||
|
||||
**Visual context:** Database schema shown with fields: session_id/project_id, user_id, timestamp, msg.
|
||||
|
||||
---
|
||||
|
||||
### File Lifecycle and Cleanup
|
||||
**[37:50 — 42:12]**
|
||||
|
||||
The team discussed file retention policy within chats:
|
||||
|
||||
- **Decision:** Files inside chats live for **3 days** by default
|
||||
- Track `last_read`/`last_update` timestamps
|
||||
- After 3 days without access, files are auto-deleted
|
||||
- If a user needs a deleted file, the bot asks them to re-send it
|
||||
- For inactive accounts: delete entire workspace after N months (like Telegram's 6-month inactivity deletion)
|
||||
- Artifacts generated by the agent are deleted after being sent to the user via messenger
|
||||
|
||||
> **Azamat** @ 40:20: "Условно сделаем хранение три дня файлов, то есть если три дня никто их не трогает."
|
||||
|
||||
> **Azamat** @ 48:33: "Давай просто как у телеграма. Если профиль не активен 3 месяца, он удаляет аккаунт."
|
||||
|
||||
---
|
||||
|
||||
### Responsibilities and Team Boundaries
|
||||
**[43:00 — 43:43]**
|
||||
|
||||
The team explicitly marked areas of responsibility on the Excalidraw diagram. The green-highlighted sections (Telegram/Discord/Slack integrations and Stream) are **not their responsibility** — those belong to "Путиловский-team" (Putilovsky's team). Lambda Lab 3.0 owns the Master, AI-Agent, workspace, and tools infrastructure.
|
||||
|
||||
**Visual context:** Diagram annotated with "Путиловский-team" labels on the Stream/integration components.
|
||||
|
||||
---
|
||||
|
||||
### Machine-Level Architecture
|
||||
**[44:29 — 47:01]**
|
||||
|
||||
Egor suggested visualizing the machine-level architecture: a Linux base, shared environment layer with lambda-tools, then multiple Agent-AI containers above, each with their own environment and code layer. This shows how lambda tools are shared across all agents on a machine, while each agent has its own isolated workspace.
|
||||
|
||||
**Visual context:** New Excalidraw section labeled "Машина" (Machine) showing: Linux -> Env -> lambda-tools -> multiple Agent-AI instances.
|
||||
|
||||
---
|
||||
|
||||
### Storage Overcommit Discussion
|
||||
**[49:16 — 51:32]**
|
||||
|
||||
Azamat suggested that the 10GB per user wouldn't be physically reserved — similar to VPS overcommit, they'd simply check that each user's directory doesn't exceed 10GB. If a machine runs out of space, Kubernetes can migrate workloads to another node. The team agreed this is acceptable for the initial version and deferred detailed capacity planning.
|
||||
|
||||
> **Azamat** @ 49:26: "Мы просто их будем создавать на диске и смотреть, что папка пользователей не больше 10 гигавайт."
|
||||
|
||||
---
|
||||
|
||||
### Container Lifecycle and TTL
|
||||
**[55:44 — 56:10]**
|
||||
|
||||
When a user sends their first message, a container spins up. The container has a **TTL** — if there are no messages for about an hour, the container is killed. When the user returns, a new container is launched with the same mounted workspace data, so everything persists.
|
||||
|
||||
> **Azamat** @ 55:55: "У него есть какой-то TTL. Ну, типа, если там сообщений нет час, ну, контейнер сдохнет."
|
||||
|
||||
---
|
||||
|
||||
### Testing Strategy
|
||||
**[52:40 — 53:25]**
|
||||
|
||||
The question of testing without integrations was raised. Since the Telegram/Discord/Slack integration is another team's responsibility, testing the AI-Agent would require generating mock events. Azamat suggested using AI tools to quickly generate test client instruments.
|
||||
|
||||
---
|
||||
|
||||
### Repository Structure
|
||||
**[53:28 — 54:17]**
|
||||
|
||||
The team decided on **two repositories**: one for Master, one for AI-Agent. Both will be hosted on Forgejo (their self-hosted Git platform). The architecture document and repository structure are due by Friday (per Kalinin's report).
|
||||
|
||||
> **Azamat** @ 53:54: "Написано в отчете: команда к пятнице — предоставить структуру репозитория и архитектурный документ."
|
||||
|
||||
---
|
||||
|
||||
### Infrastructure: Forgejo, Matrix, Communication
|
||||
**[57:06 — 1:03:34]**
|
||||
|
||||
- **Forgejo** — self-hosted Git service at lambda.coredump.ru, used instead of GitHub for code privacy and Docker registry access
|
||||
- **Matrix** — team communication platform, registration at element.lambda.coredump.ru (E2E encryption disabled on server). To be used as backup if Telegram gets blocked.
|
||||
- The team discussed registering on both platforms
|
||||
|
||||
> **Azamat** @ 1:01:01: "Наш личный гитаб."
|
||||
|
||||
**Visual context:** Forgejo landing page showing "MAI Lambda Lab 3.0" with self-hosted Git repository features. Telegram chat showing Matrix registration instructions.
|
||||
|
||||
---
|
||||
|
||||
### Agent-Browser Tool
|
||||
**[1:12:11 — 1:15:32]**
|
||||
|
||||
The team discussed the agent-browser tool — a CLI tool for browser automation. They reviewed the GitHub repository for an open-source agent-browser (23.6k stars, Rust-based, ~1MB binary). Key concern: Chromium dependency (~800MB + RAM usage).
|
||||
|
||||
**Decision:** Start with running the browser tool locally inside the container. If it proves too heavy, move to a separate API-based service.
|
||||
|
||||
> **Azamat** @ 1:14:51: "Давай по умолчанию, ну что, вот сейчас примем решение, что оно по API ходит."
|
||||
|
||||
**Visual context:** GitHub repository page for agent-browser showing quick-start commands, installation instructions, and browser automation commands.
|
||||
|
||||
---
|
||||
|
||||
### Scripting and Tool Implementation
|
||||
**[1:16:00 — 1:19:07]**
|
||||
|
||||
Discussion about how agents should implement tools at runtime. The team considered Lua scripting as a lightweight alternative to Python for agent-generated scripts, avoiding dependency issues. The idea is that the agent writes small scripts to process data without needing to call the LLM again for each step.
|
||||
|
||||
> **Azamat** @ 1:18:43: "Проще питон, потому что у вас питон уже будет поднятый."
|
||||
|
||||
---
|
||||
|
||||
### Security: Prompt Injection and Data Leakage
|
||||
**[1:19:27 — 1:23:58]**
|
||||
|
||||
Extended discussion about security risks:
|
||||
|
||||
- **Prompt injection** — malicious prompts embedded in web pages or files could instruct the agent to exfiltrate user data
|
||||
- **File leakage** — sensitive files (e.g., NDA documents, movie scripts) uploaded by users could be leaked by a compromised agent
|
||||
- **Defense options discussed:**
|
||||
- Agent creates an execution plan before acting, which can be reviewed
|
||||
- User tools should have execute-only permissions
|
||||
- LLM-level defense is "useless" per Egor
|
||||
- **Decision:** Security is not Lambda Lab 3.0's sole responsibility — there's another team doing "LLM research" that should add **security metrics** and test defense mechanisms
|
||||
|
||||
> **Egor** @ 1:23:28: "И защищаться на уровне ЛЛМ это бесполезно."
|
||||
|
||||
> **Azamat** @ 1:23:50: "Придумать метрику безопасности."
|
||||
|
||||
---
|
||||
|
||||
### Tomorrow's Presentation and Next Steps
|
||||
**[1:24:33 — 1:30:18]**
|
||||
|
||||
The team confirmed that the Excalidraw architecture diagram is the main presentation material for the next day's meeting with Kalinin. Azamat will:
|
||||
- Set up the Forgejo repository
|
||||
- Create wiki documentation
|
||||
- Set up the architecture document
|
||||
- Share Forgejo registration links
|
||||
|
||||
The meeting ended with Azamat demonstrating his OpenCode setup — showing agent profiles (code-refactorer, bug-hunter-fixer, worker, documentation-generator, feature-developer, code-explorer, test-engineer, code-reviewer) and system-design.md configuration files that define how AI coding agents interact with the project.
|
||||
|
||||
> **Azamat** @ 1:25:09: "Касательно завтрашней презентации, мы же будем как-то вот показывать эту схему, не на пальцах же объяснять?"
|
||||
|
||||
**Visual context:** Terminal showing OpenCode CLI with Claude Opus 4.6 model, agent profiles, system-design.md configuration file showing subagent delegation rules.
|
||||
|
||||
---
|
||||
|
||||
## Decisions Made
|
||||
|
||||
| # | Decision | Context | Timestamp |
|
||||
|---|----------|---------|-----------|
|
||||
| 1 | Platform consists of two applications: Master (orchestrator) and AI-Agent (sandboxed) | Core architecture decision | 03:01 |
|
||||
| 2 | 10GB workspace per user with overcommit (not physically reserved) | Storage allocation strategy | 05:15, 49:26 |
|
||||
| 3 | Three tool categories: built-in (in agent code), lambda (platform-wide RO), user (per-user +x only) | Tool taxonomy | 07:30 |
|
||||
| 4 | Tools must support `--help`, `--json`/`--agent` flags and `man-agent` command | Tool interface contract | 10:38 |
|
||||
| 5 | User tools have execute-only permissions for security | Security measure | 16:19 |
|
||||
| 6 | Dependencies pre-mounted from host, cached in S3 | Performance optimization | 18:15 |
|
||||
| 7 | Rename "projects" to "chats" (C1, C2, C3) | Naming clarity | 37:40 |
|
||||
| 8 | Message history stored as per-chat history.db files inside workspace | Storage simplicity | 33:14 |
|
||||
| 9 | Files inside chats auto-delete after 3 days of inactivity | File lifecycle policy | 40:20 |
|
||||
| 10 | Inactive accounts deleted after N months (Telegram-style) | Account lifecycle | 48:33 |
|
||||
| 11 | Container TTL ~1 hour without messages | Resource management | 55:55 |
|
||||
| 12 | Two repositories: one for Master, one for AI-Agent | Code organization | 54:00 |
|
||||
| 13 | Use Forgejo for Git hosting | Infrastructure | 57:30 |
|
||||
| 14 | Use Matrix as backup communication (Element client) | Team communication | 1:00:37 |
|
||||
| 15 | Agent-browser starts as local tool, move to API if too heavy | Browser tool strategy | 1:14:51 |
|
||||
| 16 | Security is a shared responsibility — LLM metrics team should add security benchmarks | Security ownership | 1:23:48 |
|
||||
|
||||
## Action Items
|
||||
|
||||
| # | Owner | Task | Deadline | Timestamp |
|
||||
|---|-------|------|----------|-----------|
|
||||
| 1 | Azamat | Create Forgejo repository structure for Master and AI-Agent | Today (meeting day) | 1:00:12 |
|
||||
| 2 | Azamat | Set up wiki and upload architecture documentation | Today | 1:00:19 |
|
||||
| 3 | Azamat | Share Forgejo registration link with the team | Today | 1:01:24 |
|
||||
| 4 | Azamat | Create Matrix chat for the team | Today | 1:03:09 |
|
||||
| 5 | Azamat | Prepare architecture presentation for Kalinin | Tomorrow | 1:24:33 |
|
||||
| 6 | Team | Register on Forgejo (lambda.coredump.ru) | Today | 1:01:06 |
|
||||
| 7 | Team | Register on Matrix (element.lambda.coredump.ru) | Today | 1:00:37 |
|
||||
| 8 | Team | Define tool interface contract (--help, --json, man-agent) | Not specified | 11:15 |
|
||||
| 9 | Team | Set up dev-environment configuration (CLAUDE.md-style) | Not specified | 1:26:22 |
|
||||
| 10 | Other team | Define security metrics for LLM safety | Not specified | 1:23:50 |
|
||||
|
||||
## Key Quotes
|
||||
|
||||
> "Наша задача именно сделать агента, который живет в изолированной среде, при этом он может пользоваться какими-то тулами." — Azamat, 02:51
|
||||
|
||||
> "Мы ему выделяем 10 гигабайт памяти. Просто. И он в эти 10 гигабайт может делать, что хочет." — Azamat, 05:15
|
||||
|
||||
> "Потому что это поможет подцепить где-нибудь вирусный промпт, полезть в папку UserTools, ввести туда какой-нибудь принт токен и слить токены оттуда." — Egor, 15:58
|
||||
|
||||
> "Каждый запрос в BD, ему нужно пройтись по индексу, найти все записи вот с этим project id, а они раскиданы все по разным чанкам." — Egor, 34:45
|
||||
|
||||
> "Считай просто это как Google диск, только наш." — David, 22:08
|
||||
|
||||
> "И защищаться на уровне ЛЛМ это бесполезно." — Egor, 1:23:28
|
||||
|
||||
> "Мы же, понимаешь, у нас же, это типа за два дня накинутая просто первая архитектура. Чтобы мы начали думать в этом направлении хотя бы." — Azamat, 50:14
|
||||
|
||||
## Visual Artifacts
|
||||
|
||||
### Architecture Diagram (Excalidraw — primary artifact)
|
||||
|
||||
The main diagram evolved throughout the meeting on Excalidraw and shows the following system:
|
||||
|
||||
**Top-level architecture:**
|
||||
- **Stream layer** (Путиловский-team responsibility): Telegram, Discord, Slack integrations
|
||||
- **Docker layer**: Multiple AI-Agent containers
|
||||
- **Master**: Orchestrator connected to DB and S3
|
||||
- **S3**: Artifact/file storage
|
||||
- **DB**: Session management, metadata
|
||||
|
||||
**AI-Agent Sandbox (per-user):**
|
||||
- **Workspace 10GB** containing:
|
||||
- Chats: C1 (file1.pdf, file2.png, history.db), C2 (file3.docx, history.db), C3 (video.mp4, history.db)
|
||||
- User-tool (+x only)
|
||||
- **Mount points:**
|
||||
- `Mount cur-chat` — current chat data
|
||||
- `Mount dependencies` — cached tool dependencies
|
||||
- `Mount lambda-tools` — shared platform tools
|
||||
- **Built-in tools:** web-search, fetch-url, bash
|
||||
- **Lambda tools (RO):** markitdown (with --help, --json/--agent, man-agent interface)
|
||||
|
||||
**Machine-level view:**
|
||||
- Linux base
|
||||
- Shared Env layer
|
||||
- Lambda-tools (shared)
|
||||
- Multiple Agent-AI instances, each with own workspace
|
||||
|
||||
### ChatGPT Projects Reference
|
||||
**[36:30]** Azamat showed ChatGPT's project interface to illustrate the concept of projects containing chats with attached files.
|
||||
|
||||
### Forgejo Instance
|
||||
**[57:30]** The team's Forgejo instance at "MAI Lambda Lab 3.0" — self-hosted Git repository service.
|
||||
|
||||
### Agent-Browser GitHub Repository
|
||||
**[1:13:30]** agent-browser repository (23.6k stars, 58 releases, v0.21.2, Rust-based CLI tool for browser automation).
|
||||
|
||||
### OpenCode Agent Setup
|
||||
**[1:28:00 — 1:29:30]** Azamat's terminal showing OpenCode CLI with Claude Opus 4.6, multiple agent profiles (@code-refactorer, @bug-hunter-fixer, @worker, @documentation-generator, @feature-developer, @code-explorer, @test-engineer, @code-reviewer), and system-design.md configuration for agent behavior.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **How exactly should the tool interface contract work?** The `--help`, `--json`/`--agent` flags and `man-agent` command were proposed but not finalized.
|
||||
2. **Should user tools be writable by the agent or only loaded from external sources?** Security implications were raised but not fully resolved.
|
||||
3. **What happens when a heavy tool (like agent-browser) requires more resources than the container allows?** The "start local, move to API" approach was agreed on but details remain.
|
||||
4. **How to handle the scenario where an agent needs a library that isn't pre-installed?** The scripting discussion suggested Python is available, but library management wasn't resolved.
|
||||
5. **Security architecture:** Who is responsible for defending against prompt injection attacks? The LLM metrics team was suggested, but no formal agreement was reached.
|
||||
6. **Memory and context management:** SOUL.md/MEMORY.md-style files were mentioned but not designed.
|
||||
7. **What should the Kubernetes setup look like?** Mentioned as needed "in the second half of spring" but not planned.
|
||||
8. **Detailed flow for file lifecycle:** When exactly are S3 artifacts cleaned up? The "3-day rule" applies to workspace files, but S3 cleanup timing remains unclear.
|
||||
9. **Browser Use vs. agent-browser:** The relationship with Durevich's team regarding browser integration needs clarification.
|
||||
|
||||
## Source
|
||||
Original transcript: `meeting_1.txt`
|
||||
170
tasks.md
170
tasks.md
|
|
@ -1,142 +1,116 @@
|
|||
# План работ: web-python-skelet
|
||||
# План работ: master-service MVP sandbox
|
||||
|
||||
## Контекст
|
||||
|
||||
- Источник требований: `AGENTS.md` и ADR `docs/001`-`docs/004`
|
||||
- Текущее состояние: в `adapter/`, `domain/`, `usecase/`, `repository/`, `test/` пока только `__init__.py`
|
||||
- Отсутствуют рабочие каталоги и файлы из целевой структуры: `adapter/config/`, `adapter/otel/`, `adapter/di/`, `adapter/http/fastapi/`, `config/`, `main.py`
|
||||
- Ограничения: `docs/` и `tasks.md` не добавлять в git; коммиты не делать; работать по одной задаче
|
||||
- ADR пока покрывают архитектуру, новые ADR нужны только если по ходу работ изменится решение
|
||||
- Источники требований: `docs/master.md`, `meetings/meeting_1_document.md`, `README.md`, `docs/*`
|
||||
- Базовый template уже готов: typed config, DI container, observability, FastAPI adapter и versioned API под `/api/v1`
|
||||
- Текущая цель: минимальное управление Docker sandbox без auth
|
||||
- MVP API: `POST /api/v1/create`
|
||||
- Sandbox policy: TTL `300` секунд, одна активная sandbox на `chat_id`, повторный `create` переиспользует активную сессию
|
||||
- Volume policy: chat volume `rw`, dependencies volume `ro`, lambda-tools volume `ro`
|
||||
- Host paths вычисляются из typed config, а HTTP request передает только `chat_id`
|
||||
- Cleanup выполняется периодическим in-process loop внутри master-service
|
||||
|
||||
## Вне текущего scope
|
||||
|
||||
- auth и access control
|
||||
- p2p lease и WebSocket transport
|
||||
- workspace/chat CRUD API
|
||||
- chat files, artifacts, S3, quota и retention policy
|
||||
- центральная БД и multi-node orchestration
|
||||
|
||||
## Правила выполнения
|
||||
|
||||
- Каждую задачу выполнять отдельным заходом, без параллельной реализации
|
||||
- Каждый субагент отдает diff, список измененных файлов и проверку, но не делает commit
|
||||
- Если в задаче всплывает архитектурное изменение, остановиться и вынести вопрос на согласование
|
||||
- Выполняем по одной задаче
|
||||
- Коммиты не делаем
|
||||
- Если по ходу нужна смена архитектуры, останавливаемся и согласуем решение
|
||||
- `domain/` и `usecase/` не импортируют Docker, FastAPI, OpenTelemetry, env или YAML
|
||||
- Inner layers работают только через минимальные domain сущности и usecase порты
|
||||
|
||||
## Очередь задач
|
||||
|
||||
### T01. Базовый каркас домена и usecase
|
||||
### M01. ADR и минимальный sandbox scaffolding
|
||||
|
||||
- Исполнитель: `primary-agent` (scaffolding)
|
||||
- Статус: completed
|
||||
- Исполнитель: `primary-agent`
|
||||
- Статус: pending
|
||||
- Зависимости: нет
|
||||
- Commit required: no
|
||||
- Scope: создать базовые файлы и контракты в `domain/`, `usecase/`, `repository/`
|
||||
- Файлы: `domain/error.py`, `domain/user.py`, `usecase/interface.py`, `usecase/user.py`, `repository/user.py`
|
||||
- Критерии приемки: зависимости направлены внутрь; в `domain/` и `usecase/` нет FastAPI/OTel; есть пример сущности, ошибок, портов и простого usecase
|
||||
- Scope: зафиксировать MVP-решение в ADR и создать минимальные сущности, ошибки и usecase-контракты для sandbox orchestration
|
||||
- Файлы: `docs/006-mvp-docker-sandbox-orchestration.md`, `domain/sandbox.py`, `domain/error.py`, `usecase/interface.py`, `usecase/sandbox.py`
|
||||
- Критерии приемки: в `domain/` есть минимальная `SandboxSession` и sandbox-ошибки; в `usecase/` есть порты `SandboxSessionRepository`, `SandboxRuntime` и `Clock`; созданы скелеты `CreateSandbox` и `CleanupExpiredSandboxes`; ADR занимает 10-20 строк
|
||||
|
||||
### T02. Конфиг из YAML и env
|
||||
### M02. Typed config для sandbox runtime
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T01`
|
||||
- Статус: pending
|
||||
- Зависимости: `M01`
|
||||
- Commit required: no
|
||||
- Scope: собрать typed-config слой в `adapter/config/` и подготовить базовые yaml-файлы
|
||||
- Файлы: `adapter/config/*`, `config/app.yaml`
|
||||
- Критерии приемки: конфиг собирается в одну dataclass-структуру; секреты читаются из env; парсинг и валидация не протекают в inner layers
|
||||
- Scope: расширить typed-config слоем `sandbox` с настройками image, TTL, cleanup interval, host paths и container mount paths
|
||||
- Файлы: `adapter/config/model.py`, `adapter/config/loader.py`, `config/app.yaml`
|
||||
- Решение: chat host path строится как путь под общим `sandbox.chats_root/<chat_id>`; request не передает host path напрямую
|
||||
- Критерии приемки: конфиг собирается в typed dataclass-дерево; дефолтный TTL равен `300`; есть отдельные настройки для `chats_root`, `dependencies_host_path`, `lambda_tools_host_path`, `chat_mount_path`, `dependencies_mount_path`, `lambda_tools_mount_path`, `cleanup_interval_seconds`; inner layers не читают env
|
||||
|
||||
### T03. Observability порты и OTel adapter
|
||||
### M03. Docker runtime adapter для sandbox lifecycle
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T01`, `T02`
|
||||
- Статус: pending
|
||||
- Зависимости: `M01`, `M02`
|
||||
- Commit required: no
|
||||
- Scope: реализовать логгер, метрики, трейсинг и bootstrap OTel в `adapter/otel/` через интерфейсы из `usecase/interface.py`
|
||||
- Файлы: `adapter/otel/*`, `config/otel-collector.yaml`
|
||||
- Критерии приемки: inner layers знают только интерфейсы; OTLP exporter настраивается из конфига; нет кастомного trace middleware
|
||||
- Scope: реализовать outer adapter над Docker для создания и остановки sandbox контейнера с нужными labels и mount policy
|
||||
- Файлы: `adapter/docker/runtime.py`, `adapter/docker/__init__.py`
|
||||
- Ограничения: все Docker-детали остаются в `adapter/`; runtime не должен протекать во внутренние слои
|
||||
- Критерии приемки: runtime умеет создать sandbox container по входным параметрам usecase; chat volume монтируется как `rw`; dependency и lambda-tools volumes монтируются как `ro`; контейнер получает labels с `session_id`, `chat_id` и `expires_at`; runtime переводит ошибки Docker в понятные исключения адаптера
|
||||
|
||||
### T04. Composition root и lifetime singleton-объектов
|
||||
### M04. In-memory session repository и usecase `CreateSandbox`
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T01`, `T02`, `T03`
|
||||
- Статус: pending
|
||||
- Зависимости: `M01`, `M02`, `M03`
|
||||
- Commit required: no
|
||||
- Scope: собрать контейнер и startup wiring в `adapter/di/`
|
||||
- Файлы: `adapter/di/container.py`, `adapter/di/__init__.py`
|
||||
- Критерии приемки: repository/usecase создаются один раз на старте; контейнер хранит инстансы явно; нет пересоздания на HTTP-запрос
|
||||
- Scope: реализовать in-memory registry активных sandbox-сессий и usecase создания sandbox с логикой reuse по `chat_id`
|
||||
- Файлы: `repository/sandbox_session.py`, `usecase/sandbox.py`, `adapter/di/container.py`
|
||||
- Решение: если по `chat_id` есть неистекшая сессия, usecase возвращает ее без нового container start; если сессия истекла, usecase инициирует stop старой sandbox и создает новую
|
||||
- Критерии приемки: одна активная sandbox на `chat_id`; TTL-логика использует порт `Clock`; usecase не импортирует Docker; container wiring остается singleton-based
|
||||
|
||||
### T05. FastAPI adapter как заменяемый web layer
|
||||
### M05. Cleanup expired sandboxes и lifecycle wiring
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T04`
|
||||
- Статус: pending
|
||||
- Зависимости: `M04`
|
||||
- Commit required: no
|
||||
- Scope: поднять HTTP adapter в `adapter/http/fastapi/` с app factory, lifespan, dependencies, middleware и router ` /api/v1`
|
||||
- Файлы: `adapter/http/fastapi/*`, `main.py`
|
||||
- Критерии приемки: FastAPI изолирован в adapter-слое; handlers тонкие; request logging и metrics middleware подключены; usecase/repository берутся из контейнера
|
||||
- Scope: реализовать usecase cleanup просроченных sandbox и подключить периодический cleanup loop в FastAPI lifecycle
|
||||
- Файлы: `usecase/sandbox.py`, `adapter/di/container.py`, `adapter/http/fastapi/app.py`, при необходимости `adapter/http/fastapi/dependencies.py`
|
||||
- Ограничения: не ломать ADR про раннее OTel instrumentation; lifecycle loop должен стартовать и останавливаться один раз
|
||||
- Критерии приемки: cleanup находит истекшие сессии, останавливает sandbox через runtime и удаляет их из registry; интервал cleanup берется из конфига; shutdown корректно завершает фоновую задачу
|
||||
|
||||
### T06. Локальный runtime и compose-окружение
|
||||
### M06. HTTP endpoint `POST /api/v1/create`
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T02`, `T03`, `T05`
|
||||
- Статус: pending
|
||||
- Зависимости: `M04`
|
||||
- Commit required: no
|
||||
- Scope: добавить контейнерный runtime для сервиса и compose-окружение с OTel и UI для просмотра логов, метрик и трейсов
|
||||
- Файлы: `Dockerfile`, `docker-compose.yml`
|
||||
- Ограничения: не трогать репозиторный `config/app.yaml`; docker должен прокидывать свой runtime-config внутрь контейнера; Dockerfile только с двумя стадиями `build` и `run`
|
||||
- Критерии приемки: `make compose-build` и `make compose-up` опираются на существующие файлы; сервис поднимается в контейнере; OTel telemetry уходит в dockerized stack; есть UI для просмотра логов, метрик и трейсов; для локального docker-окружения достаточно только `Dockerfile` и `docker-compose.yml`
|
||||
- Scope: добавить минимальную HTTP ручку для создания или переиспользования sandbox без auth
|
||||
- Файлы: `adapter/http/fastapi/schemas.py`, `adapter/http/fastapi/dependencies.py`, `adapter/http/fastapi/routers/v1/router.py`, при необходимости `adapter/di/container.py`
|
||||
- Request: `{ "chat_id": "..." }`
|
||||
- Response: `session_id`, `chat_id`, `container_id`, `status`, `expires_at`
|
||||
- Критерии приемки: router остается тонким; handler только переводит HTTP input в команду usecase и маппит ошибки в HTTP; endpoint живет под `/api/v1/create`; auth не добавляется
|
||||
|
||||
### T07. Тесты на lifetimes, config и HTTP smoke
|
||||
### M07. Тесты для create, reuse, TTL и mount policy
|
||||
|
||||
- Субагент: `test-engineer`
|
||||
- Статус: pending
|
||||
- Зависимости: `T01`, `T02`, `T03`, `T04`, `T05`, `T06`
|
||||
- Зависимости: `M03`, `M04`, `M05`, `M06`
|
||||
- Commit required: no
|
||||
- Scope: покрыть тестами ключевые архитектурные гарантии
|
||||
- Scope: покрыть тестами ключевое поведение MVP без запуска реального production Docker stack
|
||||
- Файлы: `test/*`
|
||||
- Критерии приемки: есть тест на singleton lifetime для repository/usecase; есть тест merge YAML+env; есть smoke-тест для ` /api/v1`; тесты не тянут FastAPI/OTel в inner layers
|
||||
- Критерии приемки: есть unit-тесты для `CreateSandbox` и `CleanupExpiredSandboxes` с fake clock; есть HTTP smoke-тест для `POST /api/v1/create`; есть adapter-level тест с mock Docker client на mount policy `chat=rw`, `deps=ro`, `tools=ro`; тесты не тащат FastAPI или Docker в inner-layer тесты
|
||||
|
||||
### T08. Архитектурный и boundary review
|
||||
### M08. Архитектурный и boundary review по MVP sandbox
|
||||
|
||||
- Субагент: `code-reviewer`
|
||||
- Статус: pending
|
||||
- Зависимости: `T07`
|
||||
- Зависимости: `M07`
|
||||
- Commit required: no
|
||||
- Scope: проверить импорты, соблюдение слоев, startup lifetimes и заменяемость web adapter
|
||||
- Scope: проверить соблюдение clean architecture, dependency direction и соответствие MVP-ограничениям
|
||||
- Файлы: весь измененный код
|
||||
- Критерии приемки: dependency direction не нарушен; FastAPI и OTel не протекают в `domain/` и `usecase/`; замечания сформулированы как точечные правки или подтверждение готовности к review
|
||||
|
||||
### T09. Конфигурируемый runtime observability
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T03`, `T04`, `T05`
|
||||
- Commit required: no
|
||||
- Scope: сделать конфигурируемый runtime observability с настраиваемым sink и форматом логов, плюс отдельными флагами для метрик и трейсов
|
||||
- Файлы: `adapter/config/*`, `adapter/observability/*`, `adapter/otel/*`, `adapter/di/*`, `adapter/http/fastapi/*`, `config/app.yaml`, при необходимости `main.py`
|
||||
- Конфиг: `logging.output=stdout|file|otel`, `logging.format=text|json`, `logging.file_path=...`, `metrics.enabled=true|false`, `tracing.enabled=true|false`
|
||||
- Решение: вынести выбор runtime в отдельный adapter-layer factory; `domain/` и `usecase/` не менять; для `stdout` и `file` поддержать оба формата `text` и `json`; `logging.file_path` использовать только при `logging.output=file`; при отключенных метриках и трейсах использовать `Noop`-реализации; OTel runtime поднимать только если нужен хотя бы для одного сигнала
|
||||
- Критерии приемки: при `logging.output=stdout` логи идут в stdout в формате `text` или `json` по конфигу; при `logging.output=file` логи пишутся в файл по пути `logging.file_path` в формате `text` или `json`; при `logging.output=otel` логи уходят в collector; `metrics.enabled=false` отключает метрики и metrics middleware; `tracing.enabled=false` отключает FastAPI instrumentation и tracer runtime; DI продолжает отдавать единый runtime через контейнер; внутренние слои по-прежнему знают только порты
|
||||
|
||||
### T10. ADR: раннее подключение OTel к FastAPI
|
||||
|
||||
- Исполнитель: `primary-agent` (docs)
|
||||
- Статус: completed
|
||||
- Зависимости: нет
|
||||
- Commit required: no
|
||||
- Scope: зафиксировать правило, что FastAPI OTel instrumentation выполняется до первой сборки `middleware_stack`
|
||||
- Файлы: `docs/005-fastapi-otel-early-instrumentation.md`
|
||||
- Критерии приемки: ADR занимает 10-20 строк; описаны context, decision, consequences; решение не переписывает историю прошлых ADR
|
||||
|
||||
### T11. Перенос FastAPI OTel bootstrap в app factory
|
||||
|
||||
- Субагент: `feature-developer`
|
||||
- Статус: completed
|
||||
- Зависимости: `T10`
|
||||
- Commit required: no
|
||||
- Scope: перенести создание container, установку `FastAPIInstrumentor.instrument_app(...)` из `lifespan` в `create_app`, оставив в `lifespan` только shutdown
|
||||
- Файлы: `adapter/http/fastapi/app.py`, `adapter/http/fastapi/lifespan.py`, при необходимости `adapter/http/fastapi/dependencies.py`
|
||||
- Ограничения: не использовать ручной rebuild `app.middleware_stack`; не менять `domain/` и `usecase/`; не добавлять бизнес-логику; сохранить singleton-lifetime container
|
||||
- Критерии приемки: instrumentation происходит до первой сборки middleware stack; `OpenTelemetryMiddleware` попадает в runtime stack без workaround; shutdown закрывает instrumentation и runtime один раз; compose-конфиг продолжает работать
|
||||
|
||||
### T12. Регрессионная проверка HTTP telemetry wiring
|
||||
|
||||
- Субагент: `test-engineer`
|
||||
- Статус: pending
|
||||
- Зависимости: `T11`
|
||||
- Commit required: no
|
||||
- Scope: добавить проверку, что раннее instrumentation wiring сохраняется и не требует ручного rebuild middleware stack
|
||||
- Файлы: `test/*`
|
||||
- Ограничения: без реального collector; проверять через ASGI/lifespan или локальные assertions по app runtime; не тянуть FastAPI и OTel в inner-layer тесты
|
||||
- Критерии приемки: тест подтверждает, что при включенных metrics/tracing `OpenTelemetryMiddleware` присутствует в runtime stack; тест не зависит от внешнего OTel collector; существующие архитектурные границы не нарушены
|
||||
- Критерии приемки: Docker остается только во внешнем adapter; FastAPI не протекает в `domain/` и `usecase/`; TTL и mount policy читаются как явные, тестируемые правила; замечания сформулированы как точечные правки или подтверждение готовности
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue