Lambda Lab 3.0 — Surfaces

What This Is

Surfaces (поверхности) — это тонкие адаптеры-клиенты, соединяющие мессенджеры с агентами платформы Lambda. Текущая и главная реализация — Matrix MVP. Бот работает как stateless-прослойка: преобразует события Matrix во внутренний протокол core/ и маршрутизирует их на внешние контейнеры агентов (через AgentApi по WebSocket).

Core Value

Пользователь может бесшовно взаимодействовать с изолированными AI-агентами через нативные интерфейсы мессенджеров (с поддержкой пересылки файлов и работы в комнатах), в то время как сама платформа агентов не зависит от транспорта.

Requirements

Validated

✓ core/ — унифицированный протокол событий, EventDispatcher, StateStore, ChatManager.
✓ adapter/matrix/ — Space+rooms адаптер. Прием инвайтов, автосоздание иерархии комнат, команды !new, !archive, !clear, !yes/!no.
✓ sdk/real.py — интеграция с AgentApi. Поддержка WebSocket для обмена сообщениями и передачи вложений в обе стороны.
✓ Shared Volume — прямая передача файлов в локальные рабочие папки агентов (/agents/).
✓ Dynamic Routing — маршрутизация чатов к агентам на основе config/matrix-agents.yaml.
✓ Deployment — Разделение окружений на docker-compose.prod.yml (только бот) и docker-compose.fullstack.yml (бот + локальный агент для E2E).

Out of Scope / Deferred

E2EE для Matrix (отложено из-за сложностей сборки python-olm на кросс-платформенных средах).
Интеграция с Master-сервисом платформы (временно используется прямое соединение с platform-agent через AgentApi).
Telegram-адаптер (вынесен в легаси ветку feat/telegram-adapter, MVP фокусируется на Matrix).

Context

Стек: Python 3.11+, matrix-nio, uv, pydantic.
Бот хранит только локальную привязку (room_id <-> platform_chat_id) в SQLite. Вся долговременная память и история диалогов хранятся на стороне агента.
Жизненный цикл контейнеров агентов управляется платформой, а не ботом.

Key Decisions

Decision	Rationale	Outcome
Space+rooms для Matrix	Room-based UX и явные чаты (по одному на тред) удобнее, чем DM-каша	✓ Good
Прямая интеграция AgentApi	Master API не был готов, прямое WebSocket соединение позволяет передавать стейт и файлы	✓ Good
Shared Volume для файлов	Избавляет от необходимости гонять base64 по сети, быстрый прямой доступ к файлам	✓ Good
Stateless бот	Бот легко перезапускать и масштабировать, память изолирована в агентах	✓ Good

Evolution

After each phase transition:

Requirements invalidated? → Move to Out of Scope with reason
Requirements validated? → Move to Validated with phase reference
New requirements emerged? → Add to Active
Decisions to log? → Add to Key Decisions

Last updated: 2026-05-03 after codebase consolidation

4.1 KiB Raw Permalink Blame History Unescape Escape