From be4607b42247e221e254c2631dc78d3566862801 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Thu, 23 Apr 2026 14:53:30 +0300 Subject: [PATCH 01/55] wip: 04-matrix-mvp-shared-agent-context-and-context-management-comma paused at task 3/3 --- .planning/HANDOFF.json | 71 +++++++--------- .../.continue-here.md | 81 +++++++------------ 2 files changed, 56 insertions(+), 96 deletions(-) diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json index 25f1d19..a0e2123 100644 --- a/.planning/HANDOFF.json +++ b/.planning/HANDOFF.json @@ -1,6 +1,6 @@ { "version": "1.0", - "timestamp": "2026-04-21T22:33:11.666Z", + "timestamp": "2026-04-23T11:46:45.938Z", "phase": "04", "phase_name": "Matrix MVP: shared agent context and context management commands", "phase_dir": ".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma", @@ -17,91 +17,74 @@ }, { "id": 2, - "name": "Перевести transport layer на thin adapter над pinned upstream AgentApi и обновить тесты/документацию", + "name": "Локализовать missing-first-chunk bug, оформить финальный bug report и очистить runtime до thin upstream integration boundary", "status": "done", "commit": "0c2884c" }, { "id": 3, - "name": "Провести финальную локализацию streaming bug и зафиксировать platform-side diagnosis в подробном отчёте", + "name": "Перейти на direct upstream AgentApi per request, убрать local wrapper из prod path и зафиксировать AGENT_BASE_URL как основной runtime contract", "status": "done", - "commit": "0c2884c" + "commit": "7d58dd1" } ], "remaining_tasks": [ { "id": 4, - "name": "Передать платформенной команде финальный bug report и дождаться triage/fix proposal", + "name": "Решить, закрываем ли Phase 04 окончательно или продолжаем Matrix через live smoke в реальном окружении", "status": "not_started" }, { "id": 5, - "name": "После ответа платформы решить follow-up phase для surfaces hardening: tokens_used optional, bounded session cache, import/config cleanup, protocol contract tests", + "name": "Если двигаемся дальше по Matrix, прогнать text/tool/file smoke на direct AgentApi per-request path и проверить отсутствие regressions", "status": "not_started" }, { "id": 6, - "name": "После platform fix повторно прогнать Matrix live smoke на text/tool/file/image сценариях", + "name": "Если начинаем новую surface, открыть follow-up phase для prod messenger architecture без собственного transport layer", "status": "not_started" } ], "blockers": [ { - "description": "После tool/file flow начало ответа может пропадать; raw logs показывают, что первый повреждённый MsgEventTextChunk уже рождается внутри platform-agent до websocket-клиента", - "type": "external", - "workaround": "Только документирование и platform bug report; локально больше не лечить transport hacks" - }, - { - "description": "platform-agent отправляет duplicate END", - "type": "external", - "workaround": "Не чинить в surfaces; держать как известный platform-side дефект до upstream исправления" - }, - { - "description": "Image path падает на больших data URI (>10 MB) и сопровождается WS 1009", - "type": "external", - "workaround": "Удалять oversized staged attachments и предупреждать пользователя; root fix только на платформе" - }, - { - "description": "tokens_used остаётся 0, потому что pinned platform-agent_api.AgentApi не публикует MsgEventEnd наружу", - "type": "external", - "workaround": "Считать текущее значение неизвестным; не городить локальные костыли" + "description": "В worktree остаётся посторонний локальный diff в core/handlers/message.py, не связанный с direct AgentApi fix", + "type": "technical", + "workaround": "Не смешивать с runtime/surface работой без отдельной задачи; handoff commit этот файл не включает" } ], "human_actions_pending": [ { - "action": "Отправить платформенной команде финальный отчёт docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md", - "context": "Это основной артефакт с итоговым аудиторским выводом и raw evidence", - "blocking": true + "action": "Выбрать следующий трек: Matrix live validation или планирование новой prod surface вроде Telegram/Max", + "context": "Кодовый фикс уже сделан и запушен; дальше работа зависит от продуктового направления, а не от transport-debug", + "blocking": false }, { - "action": "Решить, оформлять ли отдельную follow-up phase в roadmap под production cleanup surfaces после platform triage", - "context": "Сейчас реализация признана рабочей, но проблемной; часть hardening-задач осознанно отложена", + "action": "При следующем отдельном planning/cleanup коммите привести STATE/roadmap в полное соответствие с direct upstream per-request решением", + "context": "Локальный STATE уже обновлён как checkpoint, но handoff WIP commit включает только HANDOFF и .continue-here", "blocking": false } ], "decisions": [ { - "decision": "Не патчить vendored platform repos для рабочей реализации; все platform-side изменения использовались только как временная локальная диагностика и были откатаны", - "rationale": "Нужна чистая граница ответственности между surfaces и платформой", + "decision": "Для prod path Matrix surface больше не держит собственный transport layer; используется прямой upstream AgentApi с fresh connection per request", + "rationale": "Это убрало reuse-sensitive загрязнение между запросами, после чего missing-first-chunk симптом перестал воспроизводиться локально", "phase": "04" }, { - "decision": "Оставить transport layer максимально thin: AgentApiWrapper только строит клиента на chat_id, а stream semantics принадлежат upstream AgentApi", - "rationale": "Так проще локализовать баги и не смешивать platform bugs с локальными workaround’ами", + "decision": "AGENT_BASE_URL принят как основной runtime contract; AGENT_WS_URL оставлен только как backward-compat fallback в env wiring", + "rationale": "Так surface говорит с платформой по их реальному API contract, а не через локальный ws shim", "phase": "04" }, { - "decision": "Считать текущую Matrix real integration рабочей, но проблемной из-за upstream streaming/image bugs", - "rationale": "Live flow в целом работает, однако после tool/file path есть подтверждённые platform-side дефекты", - "phase": "04" - }, - { - "decision": "Не лечить missing-first-chunk локальными transport hacks повторно", - "rationale": "После cleanup и raw tracing корень локализован на стороне platform-agent; дальнейшие локальные обходы только размоют диагностику", + "decision": "Для следующих surfaces не строить custom transport wrapper поверх платформы", + "rationale": "Surface должна владеть integration/session boundary, а не альтернативной stream semantics", "phase": "04" } ], - "uncommitted_files": [], - "next_action": "Начать с отправки финального bug report платформенной команде; до их triage не менять transport semantics в surfaces повторно", - "context_notes": "Сессия завершилась полной очисткой transport layer до thin adapter, обновлением README, финальным bug report и подтверждением через raw logs, что повреждённый первый chunk рождается внутри platform-agent до websocket-клиента. Рабочая ветка clean, последние meaningful commits: 0c2884c и 4524a6a. Если продолжать работу в surfaces без ответа платформы, единственный разумный фронт — инфраструктурный hardening вокруг known limitations, а не ещё одна попытка локально чинить поток." + "uncommitted_files": [ + ".planning/STATE.md", + "core/handlers/message.py" + ], + "next_action": "При возобновлении сначала прочитать обновлённый handoff, затем выбрать один из двух треков: либо Matrix live smoke на direct AgentApi per-request path, либо новая phase/spec для prod surface без собственного transport layer", + "context_notes": "Старый checkpoint про platform triage устарел. После диалога с платформой runtime переведён на прямой upstream AgentApi с fresh connection per request, локальный wrapper убран из prod path, tests прошли, commit 7d58dd1 запушен в origin/feat/matrix-direct-agent-prototype. Важный вывод для будущей архитектуры surfaces: upstream transport считать authoritative, а локально держать только lifecycle, serialization, attachment forwarding, error mapping и reconciliation." } diff --git a/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md b/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md index 576296b..a009302 100644 --- a/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md +++ b/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md @@ -3,83 +3,60 @@ phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma task: 3 total_tasks: 3 status: paused -last_updated: 2026-04-21T22:33:11.666Z +last_updated: 2026-04-23T11:46:45.938Z --- -Phase 04 как MVP-фаза по сути закрыта: Matrix real backend работает, transport layer очищен до thin adapter над pinned upstream `platform-agent_api.AgentApi`, ветка чистая и запушенная. Текущее состояние зафиксировано как "working but problematic": после tool/file flow остаётся подтверждённый upstream bug платформы, из-за которого начало ответа может пропадать. - -Ключевой результат последней сессии: raw tracing показал, что первый повреждённый `MsgEventTextChunk` появляется уже внутри `platform-agent` до websocket-клиента. Это сняло основное подозрение с `surfaces`. +Phase 04 кодово стабилизирована вокруг direct upstream `AgentApi` per request. Коммит `7d58dd1` уже запушен в `origin/feat/matrix-direct-agent-prototype`. Старый checkpoint в этом файле устарел: после обратной связи от платформы мы убрали extra wrapper из prod path, перестали переиспользовать один websocket между запросами и после этого missing-first-chunk симптом перестал воспроизводиться локально. -- Переведён `sdk/agent_api_wrapper.py` в тонкий factory/shim без собственной stream-semantics. -- Переведён `sdk/real.py` на pinned upstream contract: без post-END drain, без custom listener, без локальной реконструкции стрима. -- Обновлены тесты под новый transport layer: - - `tests/platform/test_real.py` - - `tests/adapter/matrix/test_dispatcher.py` - - `tests/core/test_integration.py` -- README обновлён под новое состояние интеграции и known limitations. -- Создан финальный отчёт: `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`. -- Временная диагностика в vendored `platform-agent` и `platform-agent_api` была использована только для расследования и полностью удалена; nested repos снова clean. -- Последний кодовый commit с рабочим состоянием: `0c2884c` (`refactor: use thin upstream transport adapter`). +- Весь ранее собранный Matrix MVP контекст остаётся валидным: numeric `platform_chat_id`, staged attachments, shared workspace, context commands и Docker packaging уже на месте. +- Продовый runtime path переведён на direct upstream client через `sdk/upstream_agent_api.py`; локальный `sdk/agent_api_wrapper.py` удалён из runtime path. +- `sdk/real.py` теперь на каждый `send_message` и `stream_message` создаёт новый `AgentApi`, делает `connect()`, читает stream и сразу `close()`. +- `AGENT_BASE_URL` зафиксирован как основной runtime contract; `AGENT_WS_URL` оставлен только как backward-compat fallback в env wiring. +- Добавлена регрессия на reuse-sensitive missing-first-chunk сценарий и обновлены runtime/integration tests; `uv run pytest tests -q` прошёл (`196 passed`), `ruff` на затронутых файлах clean. +- Кодовый фикс закоммичен и запушен: `7d58dd1` (`fix: use direct agent api per request`). +- В сессионных выводах зафиксирован новый архитектурный принцип для следующих surfaces: не строить свой transport layer, держать только thin integration/session boundary над upstream transport. -- Передать платформенной команде финальный отчёт и дождаться triage/fix proposal. -- После ответа платформы решить, открываем ли отдельную follow-up phase для production hardening в `surfaces`. -- После platform fix повторить live smoke: - - text-only - - staged attachments - - tool/file flow - - large image failure path +- Перед следующим кодом выбрать направление: + - если продолжаем Matrix, прогнать live smoke в реальном окружении на text/tool/file flow и проверить отсутствие regressions на direct per-request path; + - если переходим к Telegram/Max-подобной работе, открыть новую phase/spec под prod surface architecture. +- Привести `.planning/STATE.md` и roadmap в полностью каноничное состояние отдельным planning/cleanup шагом, если хотим закрепить этот checkpoint не только через handoff. +- Не смешивать дальнейшую surface/runtime работу с отдельным локальным diff в `core/handlers/message.py`, пока это не станет явной задачей. -- Больше не трогать vendored platform repos ради рабочей реализации. -- Больше не добавлять локальные transport hacks, маскирующие streaming bug. -- Считать текущий missing-first-chunk баг platform-side дефектом до опровержения raw evidence. -- Оставить `tokens_used=0` как честное ограничение current upstream contract, не симулировать это значение локально. +- Matrix prod path должен использовать прямой upstream `AgentApi`, а не surface-owned wrapper с кастомной stream semantics. +- Fresh connection per request принят как дефолтный lifecycle для этой surface, потому что именно reuse websocket оказался чувствительной точкой для missing-first-chunk симптома. +- `AGENT_BASE_URL` это честный runtime contract; ws URL normalization допустим только как backward-compat env fallback. +- Для следующих surfaces надо думать терминами `integration boundary` и `runtime contract`, а не терминами "написать свой transport layer". -- Platform-side streaming bug: после tool/file flow начало ответа может пропадать. -- Duplicate `END` на стороне платформы. -- Image path на больших вложениях падает с `data-uri > 10 MB` и `WS 1009`. -- Без ответа платформенной команды дальнейший transport-layer surgery в `surfaces` не имеет инженерного смысла. +- Подтверждённого локального Matrix blocker после `7d58dd1` больше нет; дальше это вопрос product direction и live validation, а не active transport-firefight. +- В worktree остаётся посторонний локальный diff в `core/handlers/message.py`; не смешивать его с будущими surface/runtime изменениями без отдельной задачи. -Важная ментальная модель: +Важная ментальная модель теперь такая: -- `surfaces` сейчас максимально близок к upstream transport semantics. -- Если снова полезет corruption чанков, исходная презумпция должна быть "сначала смотреть platform-agent", а не придумывать новый локальный workaround. -- Главные артефакты для чтения перед продолжением: - 1. `README.md` - 2. `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md` - 3. `sdk/agent_api_wrapper.py` - 4. `sdk/real.py` - 5. `tests/platform/test_real.py` - -Если придётся продолжать без платформы, разумные задачи уже не про баг с чанками, а про clean/prod-ready улучшения вокруг него: - -- сделать `tokens_used` optional в локальном контракте -- развести `RealPlatformClient` на pool/adapter слои -- добавить bounded session cache / idle eviction -- убрать `sys.path` import hack в пользу нормальной dependency wiring -- переименовать конфиг `AGENT_WS_URL` в более честный `AGENT_BASE_URL` -- добавить protocol contract tests против fake WS server +- upstream transport authoritative; `surfaces` владеет только lifecycle, serialization, attachment forwarding, error mapping и reconciliation. +- Старый narrative "ждём platform triage перед любыми transport changes" больше не актуален; transport change уже сделан и дал положительный эффект. +- Предыдущий handoff и текущий `STATE.md` были написаны до этого решения, поэтому их надо читать как исторический контекст, а не как последнюю истину. +- Проверка на false completion ничего критичного не показала: grep задел только фразу "compatibility placeholder" в `04-01-SUMMARY.md`, а не реальный незаполненный summary. +- Текущие локальные non-handoff diff: `.planning/STATE.md` и `core/handlers/message.py`. Start with: -1. Открыть `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md` -2. Отправить этот отчёт платформенной команде как основной артефакт -3. Не менять transport layer до получения их ответа - -Если работа продолжается автономно без ответа платформы, следующий допустимый шаг — оформлять отдельную follow-up phase на hardening `surfaces`, а не повторно "чинить" стрим локальными обходами. +1. Открыть этот обновлённый handoff, а не опираться на старый checkpoint про platform triage. +2. Выбрать трек: Matrix live smoke или новая prod-surface phase. +3. Если снова полезем в runtime, не возвращать custom transport wrapper и persistent shared websocket без очень сильной причины и регрессионных тестов. From 76230392fa39e2c03c9f6cf8fb4d25cee058b310 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Thu, 23 Apr 2026 14:56:00 +0300 Subject: [PATCH 02/55] fix: normalize attachments to core Attachment type in message handler Upstream AgentApi responses can return attachment objects that don't implement the Attachment dataclass. _to_core_attachments coerces them via duck-typing so OutgoingMessage always carries typed Attachment instances regardless of the upstream response shape. --- core/handlers/message.py | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/core/handlers/message.py b/core/handlers/message.py index d9f91cd..876754c 100644 --- a/core/handlers/message.py +++ b/core/handlers/message.py @@ -1,7 +1,35 @@ # core/handlers/message.py from __future__ import annotations -from core.protocol import IncomingMessage, OutgoingMessage, OutgoingTyping +from core.protocol import Attachment, IncomingMessage, OutgoingMessage, OutgoingTyping + + +def _infer_attachment_type(mime_type: str | None) -> str: + if not mime_type: + return "document" + if mime_type.startswith("image/"): + return "image" + if mime_type.startswith("audio/"): + return "audio" + if mime_type.startswith("video/"): + return "video" + return "document" + + +def _to_core_attachments(raw: list) -> list[Attachment]: + result = [] + for a in raw: + if isinstance(a, Attachment): + result.append(a) + else: + result.append(Attachment( + type=getattr(a, "type", None) or _infer_attachment_type(getattr(a, "mime_type", None)), + url=getattr(a, "url", None), + filename=getattr(a, "filename", None), + mime_type=getattr(a, "mime_type", None), + workspace_path=getattr(a, "workspace_path", None), + )) + return result def _start_command(platform: str) -> str: @@ -38,6 +66,6 @@ async def handle_message(event: IncomingMessage, auth_mgr, platform, chat_mgr, s chat_id=event.chat_id, text=response.response, parse_mode="markdown", - attachments=list(getattr(response, "attachments", [])), + attachments=_to_core_attachments(getattr(response, "attachments", [])), ), ] From 59fbb52c20d4082a91ea386040bdeabffeb6f633 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 12:28:53 +0300 Subject: [PATCH 03/55] docs: add matrix multi-agent and restart state specs --- ...04-24-matrix-multi-agent-routing-design.md | 302 ++++++++++++++++++ ...urface-restart-state-persistence-design.md | 244 ++++++++++++++ 2 files changed, 546 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md create mode 100644 docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md diff --git a/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md b/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md new file mode 100644 index 0000000..18ce603 --- /dev/null +++ b/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md @@ -0,0 +1,302 @@ +# Matrix Multi-Agent Routing Design + +## Goal + +Move the Matrix surface from a single hardcoded upstream agent to a user-selectable multi-agent model, while preserving the existing room-based UX and the current `PlatformClient` boundary. + +The result should be: + +- one Matrix bot can work with multiple upstream agents +- users can choose an agent from the full configured list +- each chat is bound to exactly one agent +- switching the selected agent does not silently retarget an existing chat + +## Core Decision + +The selected routing model is: + +`user.selected_agent_id + room.agent_id + room.platform_chat_id` + +This means: + +- the user has one current selected agent +- each Matrix working room stores the agent it is bound to +- each Matrix working room stores its own `platform_chat_id` +- a room never changes agent implicitly + +## Why This Decision + +The current Matrix adapter already separates: + +- user-facing room organization +- local chat labels such as `C1`, `C2`, `C3` +- platform-facing conversation identity via `platform_chat_id` + +Adding multi-agent support should preserve that shape instead of replacing it. + +If routing depended only on the current user selection, then an old room could start talking to a different agent after a switch. That would make room history and backend context hard to reason about. Binding an agent to the room keeps the conversation model explicit. + +## Scope + +This design covers: + +- agent selection by the user inside the Matrix surface +- durable storage of the selected agent +- durable storage of the room-bound agent +- routing normal messages and context commands to the correct upstream agent +- behavior when a room becomes stale after an agent switch + +This design does not cover: + +- per-agent workspace isolation +- platform-side agent lifecycle or memory persistence +- per-user allowlists for available agents +- Telegram or other surfaces + +## Configuration Model + +### Agent registry + +Available agents are defined in a local config file loaded once at bot startup. + +Example: + +```yaml +agents: + - id: agent-1 + label: Analyst + - id: agent-2 + label: Research + - id: agent-3 + label: Ops +``` + +Rules: + +- every entry must have a stable `id` +- every entry must have a user-visible `label` +- all configured agents are selectable by all users +- config changes apply only after bot restart + +### Startup validation + +If the agent config is missing, empty, or invalid, the Matrix bot must fail fast on startup with a clear operator error. + +## Durable State Model + +### User-level state + +User metadata keeps the current selected agent. + +Example `matrix_user:*` shape: + +```json +{ + "space_id": "!space:example.org", + "next_chat_index": 4, + "selected_agent_id": "agent-2" +} +``` + +Meaning: + +- `selected_agent_id` controls future chat creation and activation of an unbound room +- `selected_agent_id` does not rewrite already bound rooms + +### Room-level state + +Room metadata stores the agent bound to that chat. + +Example `matrix_room:*` shape: + +```json +{ + "room_type": "chat", + "chat_id": "C3", + "display_name": "Чат 3", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + "platform_chat_id": "42", + "agent_id": "agent-2" +} +``` + +Rules: + +- one room binds to exactly one `agent_id` +- one room binds to exactly one current `platform_chat_id` +- once a room becomes stale after an agent switch, it never becomes active again + +## Runtime Semantics + +### `!start` + +`!start` remains lightweight: + +- if no agent is selected, the bot explains that an agent must be selected before normal messaging +- if an agent is already selected, the bot reports the current selection and reminds the user that `!new` creates a new room under that agent + +### `!agent` + +Introduce an agent-selection command. + +Behavior: + +- `!agent` shows the available agent list +- agent selection stores `selected_agent_id` in user metadata +- after a successful switch, the bot tells the user that existing chats bound to another agent are stale and that `!new` is required for continued work + +The exact UI can be text-first for MVP. A richer UI can be added later without changing the state model. + +### Normal message without selected agent + +If the user has not selected an agent yet: + +- do not call the platform +- return the available agent list +- ask the user to choose one first + +### Selecting an agent inside an unbound chat + +If the current room has never been bound to any agent: + +- store the new `selected_agent_id` for the user +- bind the current room to that same `agent_id` +- allow the room to become the active working chat immediately + +This avoids forcing `!new` for the user's first usable chat. + +### `!new` + +`!new` creates a new working room under the current selected agent. + +Behavior: + +1. require `selected_agent_id` +2. create the new Matrix room +3. allocate a new `platform_chat_id` +4. store `agent_id = selected_agent_id` in the new room metadata + +### Normal message in an unbound room with selected agent + +If a room exists but has no `agent_id` yet and the user already has `selected_agent_id`: + +- bind the room to `selected_agent_id` +- ensure it has `platform_chat_id` +- continue normal message dispatch + +### Normal message in a bound room + +If the room already has `agent_id` and it matches the current selected agent: + +- route the message to that `agent_id` +- use the room's `platform_chat_id` + +### Stale room after agent switch + +If the room's bound `agent_id` differs from the user's current `selected_agent_id`: + +- do not call the platform +- treat the room as stale +- return a short message telling the user that this chat belongs to the old agent and that they must use `!new` + +### Returning to a previously selected agent + +If the user later selects an old agent again: + +- previously stale rooms do not become valid again +- the user must still create a fresh room via `!new` + +## Routing and Component Changes + +### Agent registry loader + +Add a small loader responsible for: + +- reading `agents.yaml` +- validating ids and labels +- exposing a read-only registry to runtime code + +The runtime should not parse YAML ad hoc during message handling. + +### Matrix runtime pre-check + +Before dispatching a normal message, the Matrix runtime must resolve: + +- whether the user has `selected_agent_id` +- whether the current room already has `agent_id` +- whether the room can be bound now +- whether the room is stale + +This pre-check happens before handing the message to the existing dispatcher path. + +### Real platform bridge + +The current real backend path hardcodes a single runtime-level `agent_id`. +That must be replaced with per-request routing. + +The selected design is: + +- the runtime resolves the target `agent_id` +- the platform bridge creates a fresh upstream `AgentApi` for that `agent_id` +- no long-lived `AgentApi` instances are cached by user + +This preserves the current fresh-connection-per-request behavior. + +## Error Handling + +### Missing or invalid selected agent + +If `selected_agent_id` is absent: + +- ask the user to select an agent + +If `selected_agent_id` points to an agent that no longer exists in config: + +- treat the selection as invalid +- ask the user to select again + +### Missing room binding + +If the room has no `agent_id`: + +- bind it only when the user has a valid current selection +- otherwise return the selection prompt + +### Stale room + +If the room is stale: + +- do not attempt fallback routing +- do not silently rewrite room metadata +- instruct the user to run `!new` + +### Invalid config + +If the bot cannot load a valid agent registry: + +- fail at startup +- do not start in degraded single-agent mode + +## Testing Expectations + +Tests for this design should prove: + +- config parsing and startup validation +- selecting an agent persists `selected_agent_id` +- selecting an agent inside an unbound room activates that room +- `!new` binds the new room to the selected agent +- messages in a bound room use that room's `agent_id` +- stale rooms reject normal messaging with a clear `!new` instruction +- returning to the same agent later does not revive stale rooms + +## Migration Notes + +Existing rooms may have `platform_chat_id` but no `agent_id`. + +For this MVP, treat those rooms as legacy-unbound rooms: + +- if the user has a valid selected agent, the room may be bound on first use +- if no agent is selected, the room prompts for selection first + +No automatic migration across agents is introduced. diff --git a/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md b/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md new file mode 100644 index 0000000..e9c235e --- /dev/null +++ b/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md @@ -0,0 +1,244 @@ +# Matrix Surface Restart State Persistence Design + +## Goal + +Make the Matrix surface survive a normal restart or container recreate without losing the minimal state required to keep working as a bot. + +The result should be: + +- after restart, the bot can still answer messages and execute commands +- the bot remembers the selected agent for each user +- the bot remembers which agent and `platform_chat_id` each room is bound to +- temporary UX flows may be lost without being treated as a bug + +## Core Decision + +The selected persistence model is: + +`durable surface state only` + +This means: + +- persist only the state needed for routing and normal command handling +- do not persist temporary UI and wizard state +- require persistent local storage for the surface +- do not attempt recovery if those volumes are lost + +## Why This Decision + +The Matrix surface already has two different classes of state: + +- stable local state that defines how rooms and users are routed +- temporary UX state that exists only to complete short-lived interactions + +Trying to make all temporary UX state survive restart would add complexity and edge cases without improving the core requirement: the bot should still function normally after restart. + +The chosen design keeps persistence aligned with what the surface actually owns: + +- Matrix-side metadata and routing state are durable +- agent conversation memory is the platform's responsibility +- lost local volumes are treated as environment reset, not as an auto-recovery scenario + +## Scope + +This design covers: + +- which Matrix surface data must persist across restart +- where that data lives +- how restart behavior interacts with multi-agent routing +- what state is intentionally non-durable + +This design does not cover: + +- platform-side persistence of agent memory +- workspace isolation between multiple agents +- automatic reconstruction after total local volume loss +- persistence of temporary UX flows + +## Persistence Boundary + +### Durable state + +The Matrix surface must persist: + +- `matrix_user:*` +- `matrix_room:*` +- `chat:*` +- `selected_agent_id` +- room-bound `agent_id` +- room-bound `platform_chat_id` + +This is the minimal state required so that, after restart, the surface can: + +- identify the user +- identify the room +- determine which agent should receive a message +- determine which `platform_chat_id` should be used + +### Non-durable state + +The Matrix surface does not need to persist: + +- staged attachments +- pending `!load` selection +- pending `!yes/!no` confirmation +- any temporary service UI step +- live `AgentApi` instances or connection objects + +After restart, those flows may be lost. The bot only needs to remain operational. + +## Storage Model + +### Surface durable storage + +The Matrix surface must use persistent storage for: + +- `lambda_matrix.db` +- `matrix_store` + +`lambda_matrix.db` stores the local key-value state used by the surface. +`matrix_store` stores Matrix client state needed by `nio`. + +These paths must be backed by persistent container storage in normal deployments. + +### Shared `/workspace` + +The current local runtime also uses `/workspace`, but workspace behavior is outside the scope of this design. + +For this document, the only requirement is: + +- do not make restart persistence depend on solving per-agent workspace isolation first + +## Restart Assumptions + +This design assumes: + +- normal restart or redeploy with persistent local volumes still present + +This design does not assume: + +- automatic recovery after deleting or losing those volumes + +If the relevant volumes are lost, the environment is treated as reset. + +## Data Model Requirements + +### User metadata + +User metadata remains the durable location for user-level routing state. + +Example: + +```json +{ + "space_id": "!space:example.org", + "next_chat_index": 4, + "selected_agent_id": "agent-2" +} +``` + +### Room metadata + +Room metadata remains the durable location for room-level routing state. + +Example: + +```json +{ + "room_type": "chat", + "chat_id": "C3", + "display_name": "Чат 3", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + "platform_chat_id": "42", + "agent_id": "agent-2" +} +``` + +## Runtime Semantics After Restart + +After restart, the Matrix surface must: + +1. load the durable Matrix store +2. load the durable surface key-value state +3. load the agent registry config +4. resume normal room routing using persisted `selected_agent_id`, `agent_id`, and `platform_chat_id` + +Expected behavior: + +- a user with a valid previously selected agent does not need to reselect it +- a room previously bound to an agent remains bound to that agent +- normal messages and commands continue to work + +### Lost temporary UX state + +If the bot restarts during a transient UX flow: + +- staged attachments may disappear +- pending `!load` selections may disappear +- pending confirmations may disappear + +This is acceptable and should not block normal operation after restart. + +## Interaction With Multi-Agent Routing + +The multi-agent design introduces new durable state that must survive restart: + +- `selected_agent_id` on the user +- `agent_id` on the room + +Restart persistence and multi-agent routing therefore belong together. + +Without durable storage for those fields, a restart would make room routing ambiguous. + +## Failure Handling + +### Missing durable surface store + +If the durable store paths are missing because the environment was reset: + +- do not attempt to reconstruct a full working state from scratch in this design +- treat startup as a clean environment +- allow normal onboarding flows to begin again + +### Invalid durable references + +If persisted `selected_agent_id` or room `agent_id` references an agent no longer present in config: + +- do not crash +- treat the selection or room binding as invalid +- ask the user to select a valid agent again + +### Platform conversation memory + +If the upstream platform loses agent memory across restart: + +- that is outside the surface persistence boundary +- the surface must still route correctly +- platform memory persistence remains a platform responsibility + +## Testing Expectations + +Tests for this design should prove: + +- `selected_agent_id` survives restart through durable local storage +- room `agent_id` and `platform_chat_id` survive restart through durable local storage +- the bot can route messages correctly after restart without user reconfiguration +- missing temporary UX state does not break normal messaging and command handling +- invalid persisted agent references degrade into reselection prompts rather than crashes + +## Operational Notes + +For the Matrix surface to survive restart in the intended way, deployment must persist: + +- `lambda_matrix.db` +- `matrix_store` + +This is a deployment requirement, not an optional optimization. + +The design intentionally stops there. It does not require: + +- hot reload of agent config +- recovery after total local state loss +- persistence of temporary UX flows +- a solved multi-agent workspace story From 842117900ae21ae3adddc90ce2547cf5f8d46f08 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 12:39:50 +0300 Subject: [PATCH 04/55] test: cover agent api base url suffix handling --- README.md | 2 +- tests/platform/test_agent_session.py | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 93782c6..b4b4f16 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,7 @@ Matrix бот подключается к `platform-agent` по service name, а На `2026-04-21` локальный compose runtime использует vendored upstream-версии платформы без локальных патчей: - `platform-agent`: `5e7c2df954cc3cd2f5bf8ae688e10a20038dde61` -- `platform-agent_api`: `aa480bbec5bbf8e006284dd03aed1c2754e9bbee` +- `platform-agent_api`: `8a4f4db6d36786fe8af7feefffe506d4a54ac6bd` ### 4. Staged attachments в Matrix diff --git a/tests/platform/test_agent_session.py b/tests/platform/test_agent_session.py index bda5cfe..c398e8c 100644 --- a/tests/platform/test_agent_session.py +++ b/tests/platform/test_agent_session.py @@ -9,6 +9,18 @@ def test_lambda_agent_api_module_is_importable(): assert AgentApi is not None +def test_lambda_agent_api_preserves_base_url_path_suffix(): + from sdk.upstream_agent_api import AgentApi + + api = AgentApi( + agent_id="matrix-bot", + base_url="http://platform-agent:8000/proxy/", + chat_id="chat-7", + ) + + assert api.url == "http://platform-agent:8000/proxy/v1/agent_ws/chat-7/" + + def test_agent_session_module_is_intentionally_stubbed(): contents = Path(__file__).resolve().parents[2] / "sdk" / "agent_session.py" From 32b03becc8259c2010b564fe2c761c936d5a235d Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 12:42:58 +0300 Subject: [PATCH 05/55] docs: clarify matrix multi-agent routing specs --- ...04-24-matrix-multi-agent-routing-design.md | 44 ++++++++++++++++--- ...urface-restart-state-persistence-design.md | 14 ++++++ 2 files changed, 53 insertions(+), 5 deletions(-) diff --git a/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md b/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md index 18ce603..02cc89f 100644 --- a/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md +++ b/docs/superpowers/specs/2026-04-24-matrix-multi-agent-routing-design.md @@ -23,6 +23,8 @@ This means: - each Matrix working room stores the agent it is bound to - each Matrix working room stores its own `platform_chat_id` - a room never changes agent implicitly +- the shared `PlatformClient` protocol remains unchanged +- Matrix multi-agent routing is implemented by a single routing facade that delegates to per-agent real clients ## Why This Decision @@ -156,6 +158,9 @@ If the user has not selected an agent yet: - return the available agent list - ask the user to choose one first +This is an intentional one-time routing handshake, not an accidental fallback. +In a multi-agent deployment, the surface must not silently guess which agent an unbound user should talk to. + ### Selecting an agent inside an unbound chat If the current room has never been bound to any agent: @@ -230,18 +235,35 @@ Before dispatching a normal message, the Matrix runtime must resolve: This pre-check happens before handing the message to the existing dispatcher path. -### Real platform bridge +### Routed platform client + +The selected implementation keeps the shared `PlatformClient` protocol unchanged. + +The Matrix runtime owns one routing-aware facade, for example `RoutedPlatformClient`, that implements `PlatformClient` and delegates to agent-specific real clients. + +Responsibilities: + +- resolve the current room binding from local Matrix metadata +- translate a local Matrix logical chat id into the room's `platform_chat_id` +- choose the correct per-agent delegate for the room's bound `agent_id` +- keep `get_or_create_user`, `get_settings`, and `update_settings` behavior stable for the rest of the runtime + +This keeps the multi-agent logic inside the Matrix integration boundary instead of pushing agent selection into the shared protocol. + +### Real platform bridge delegates The current real backend path hardcodes a single runtime-level `agent_id`. -That must be replaced with per-request routing. +That must be replaced with per-agent delegates hidden behind the routing facade. The selected design is: -- the runtime resolves the target `agent_id` -- the platform bridge creates a fresh upstream `AgentApi` for that `agent_id` +- `RealPlatformClient` remains the low-level direct-agent delegate for one configured `agent_id` +- the routing facade holds or creates one `RealPlatformClient` delegate per configured agent +- `send_message(...)` and `stream_message(...)` on the facade resolve the room target and forward the call to the matching delegate +- the delegate creates a fresh upstream `AgentApi` for its configured `agent_id` - no long-lived `AgentApi` instances are cached by user -This preserves the current fresh-connection-per-request behavior. +This preserves the current fresh-connection-per-request behavior while avoiding a protocol break for Telegram or other surfaces. ## Error Handling @@ -300,3 +322,15 @@ For this MVP, treat those rooms as legacy-unbound rooms: - if no agent is selected, the room prompts for selection first No automatic migration across agents is introduced. + +### Existing users without `selected_agent_id` + +Existing users upgraded from the single-agent model may have working rooms but no stored `selected_agent_id`. + +For this MVP, that is handled explicitly: + +- normal messaging is paused until the user selects an agent +- the first valid selection can bind an unbound room immediately +- the surface does not auto-assign a default agent in a multi-agent config + +This is intentional. Once more than one agent exists, silent migration would be ambiguous and could route a user to the wrong backend target. diff --git a/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md b/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md index e9c235e..1f1cc7b 100644 --- a/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md +++ b/docs/superpowers/specs/2026-04-24-matrix-surface-restart-state-persistence-design.md @@ -64,6 +64,7 @@ The Matrix surface must persist: - `matrix_user:*` - `matrix_room:*` - `chat:*` +- `PLATFORM_CHAT_SEQ_KEY` - `selected_agent_id` - room-bound `agent_id` - room-bound `platform_chat_id` @@ -74,6 +75,7 @@ This is the minimal state required so that, after restart, the surface can: - identify the room - determine which agent should receive a message - determine which `platform_chat_id` should be used +- continue allocating new `platform_chat_id` values without reusing an already issued sequence number ### Non-durable state @@ -155,6 +157,17 @@ Example: } ``` +### Platform chat sequence + +The global `PLATFORM_CHAT_SEQ_KEY` remains part of durable surface state. + +Its purpose is: + +- allocate monotonically increasing `platform_chat_id` values +- avoid reusing a previously issued platform chat identifier during normal restart or redeploy + +This sequence must be stored in the same durable surface store as the room and user metadata. + ## Runtime Semantics After Restart After restart, the Matrix surface must: @@ -186,6 +199,7 @@ The multi-agent design introduces new durable state that must survive restart: - `selected_agent_id` on the user - `agent_id` on the room +- `PLATFORM_CHAT_SEQ_KEY` in the surface store Restart persistence and multi-agent routing therefore belong together. From 37f7ce27a210251d8099e3d2b5b45e3b32b5c92e Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 12:54:30 +0300 Subject: [PATCH 06/55] Add Matrix agent registry loader --- .env.example | 1 + README.md | 9 +++- adapter/matrix/agent_registry.py | 48 +++++++++++++++++++++ config/matrix-agents.example.yaml | 5 +++ pyproject.toml | 1 + tests/adapter/matrix/test_agent_registry.py | 37 ++++++++++++++++ 6 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 adapter/matrix/agent_registry.py create mode 100644 config/matrix-agents.example.yaml create mode 100644 tests/adapter/matrix/test_agent_registry.py diff --git a/.env.example b/.env.example index 5c1cb66..e251708 100644 --- a/.env.example +++ b/.env.example @@ -6,6 +6,7 @@ MATRIX_HOMESERVER=https://matrix.org MATRIX_USER_ID=@bot:matrix.org MATRIX_PASSWORD=your_password_here MATRIX_PLATFORM_BACKEND=real +MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml # Shared workspace contract SURFACES_WORKSPACE_DIR=/workspace diff --git a/README.md b/README.md index b4b4f16..94b54db 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,7 @@ MATRIX_PASSWORD=... # или MATRIX_ACCESS_TOKEN=... # Выбор backend: mock (по умолчанию) или real (подключение к platform-agent) MATRIX_PLATFORM_BACKEND=real +MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml # compose runtime: platform-agent service name + shared /workspace AGENT_BASE_URL=http://platform-agent:8000 @@ -131,7 +132,13 @@ PROVIDER_URL=https://openrouter.ai/api/v1 PROVIDER_API_KEY=... ``` -### 3. Compose runtime +### 3. Registry агентов + +1. Скопируй `config/matrix-agents.example.yaml` в `config/matrix-agents.yaml` +2. Укажи `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` +3. Используй `!agent` в Matrix, чтобы выбрать активного upstream-агента + +### 4. Compose runtime Root `docker-compose.yml` теперь является основным локальным runtime для Matrix и platform-agent. Он поднимает `matrix-bot`, `platform-agent` и общий volume `/workspace`. diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py new file mode 100644 index 0000000..2955daf --- /dev/null +++ b/adapter/matrix/agent_registry.py @@ -0,0 +1,48 @@ +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + +import yaml + + +class AgentRegistryError(ValueError): + pass + + +@dataclass(frozen=True) +class AgentDefinition: + agent_id: str + label: str + + +class AgentRegistry: + def __init__(self, agents: list[AgentDefinition]) -> None: + self.agents = agents + self._by_id = {agent.agent_id: agent for agent in agents} + + def get(self, agent_id: str) -> AgentDefinition: + try: + return self._by_id[agent_id] + except KeyError as exc: + raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc + + +def load_agent_registry(path: str | Path) -> AgentRegistry: + raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {} + entries = raw.get("agents") + if not isinstance(entries, list) or not entries: + raise AgentRegistryError("agents registry must contain a non-empty agents list") + + agents: list[AgentDefinition] = [] + seen: set[str] = set() + for entry in entries: + agent_id = str(entry.get("id", "")).strip() + label = str(entry.get("label", "")).strip() + if not agent_id or not label: + raise AgentRegistryError("each agent entry requires id and label") + if agent_id in seen: + raise AgentRegistryError(f"duplicate agent id: {agent_id}") + seen.add(agent_id) + agents.append(AgentDefinition(agent_id=agent_id, label=label)) + return AgentRegistry(agents) diff --git a/config/matrix-agents.example.yaml b/config/matrix-agents.example.yaml new file mode 100644 index 0000000..23d4b37 --- /dev/null +++ b/config/matrix-agents.example.yaml @@ -0,0 +1,5 @@ +agents: + - id: agent-1 + label: Analyst + - id: agent-2 + label: Research diff --git a/pyproject.toml b/pyproject.toml index ccc6309..f2fc338 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,6 +16,7 @@ dependencies = [ "python-dotenv>=1.0", "httpx>=0.27", "aiohttp>=3.9", + "PyYAML>=6.0", ] [project.optional-dependencies] diff --git a/tests/adapter/matrix/test_agent_registry.py b/tests/adapter/matrix/test_agent_registry.py new file mode 100644 index 0000000..dfa9050 --- /dev/null +++ b/tests/adapter/matrix/test_agent_registry.py @@ -0,0 +1,37 @@ +from pathlib import Path + +import pytest + +from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry + + +def test_load_agent_registry_reads_yaml_entries(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-2\n" + " label: Research\n", + encoding="utf-8", + ) + + registry = load_agent_registry(path) + + assert [agent.agent_id for agent in registry.agents] == ["agent-1", "agent-2"] + assert registry.get("agent-1").label == "Analyst" + + +def test_load_agent_registry_rejects_duplicate_ids(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-1\n" + " label: Duplicate\n", + encoding="utf-8", + ) + + with pytest.raises(AgentRegistryError, match="duplicate agent id"): + load_agent_registry(path) From b53523ad6cacb7731c21426cc5043a4ce5831d87 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 12:57:00 +0300 Subject: [PATCH 07/55] Reject non-mapping agent registry entries --- adapter/matrix/agent_registry.py | 3 +++ tests/adapter/matrix/test_agent_registry.py | 12 ++++++++++++ 2 files changed, 15 insertions(+) diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index 2955daf..6a54f4a 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -1,6 +1,7 @@ from __future__ import annotations from dataclasses import dataclass +from collections.abc import Mapping from pathlib import Path import yaml @@ -37,6 +38,8 @@ def load_agent_registry(path: str | Path) -> AgentRegistry: agents: list[AgentDefinition] = [] seen: set[str] = set() for entry in entries: + if not isinstance(entry, Mapping): + raise AgentRegistryError("each agent entry requires id and label") agent_id = str(entry.get("id", "")).strip() label = str(entry.get("label", "")).strip() if not agent_id or not label: diff --git a/tests/adapter/matrix/test_agent_registry.py b/tests/adapter/matrix/test_agent_registry.py index dfa9050..2c3a705 100644 --- a/tests/adapter/matrix/test_agent_registry.py +++ b/tests/adapter/matrix/test_agent_registry.py @@ -35,3 +35,15 @@ def test_load_agent_registry_rejects_duplicate_ids(tmp_path: Path): with pytest.raises(AgentRegistryError, match="duplicate agent id"): load_agent_registry(path) + + +def test_load_agent_registry_rejects_non_mapping_entries(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - agent-1\n", + encoding="utf-8", + ) + + with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): + load_agent_registry(path) From e80122522053160cf04ea48dbd9152c188f1ccac Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:02:19 +0300 Subject: [PATCH 08/55] Tighten Matrix agent registry validation --- README.md | 2 +- adapter/matrix/agent_registry.py | 16 ++++- tests/adapter/matrix/test_agent_registry.py | 70 +++++++++++++++++++++ uv.lock | 57 +++++++++++++++++ 4 files changed, 142 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 94b54db..4a50e2c 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ PROVIDER_API_KEY=... 1. Скопируй `config/matrix-agents.example.yaml` в `config/matrix-agents.yaml` 2. Укажи `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` -3. Используй `!agent` в Matrix, чтобы выбрать активного upstream-агента +3. Этот registry нужен для будущего выбора upstream-агента; сам командный переключатель `!agent` в текущем коде ещё не реализован ### 4. Compose runtime diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index 6a54f4a..5bb99d1 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -1,7 +1,7 @@ from __future__ import annotations -from dataclasses import dataclass from collections.abc import Mapping +from dataclasses import dataclass from pathlib import Path import yaml @@ -29,8 +29,20 @@ class AgentRegistry: raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc +def _load_registry_data(path: str | Path) -> dict[str, object]: + try: + raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) + except yaml.YAMLError as exc: + raise AgentRegistryError("invalid agent registry YAML") from exc + if raw is None: + return {} + if not isinstance(raw, Mapping): + raise AgentRegistryError("agent registry must be a mapping with an agents list") + return dict(raw) + + def load_agent_registry(path: str | Path) -> AgentRegistry: - raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {} + raw = _load_registry_data(path) entries = raw.get("agents") if not isinstance(entries, list) or not entries: raise AgentRegistryError("agents registry must contain a non-empty agents list") diff --git a/tests/adapter/matrix/test_agent_registry.py b/tests/adapter/matrix/test_agent_registry.py index 2c3a705..29dd4c5 100644 --- a/tests/adapter/matrix/test_agent_registry.py +++ b/tests/adapter/matrix/test_agent_registry.py @@ -47,3 +47,73 @@ def test_load_agent_registry_rejects_non_mapping_entries(tmp_path: Path): with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): load_agent_registry(path) + + +@pytest.mark.parametrize( + "content", + [ + "", + "agents: []\n", + "agents: agent-1\n", + "foo: bar\n", + ], +) +def test_load_agent_registry_rejects_missing_non_list_and_empty_agents( + tmp_path: Path, content: str +): + path = tmp_path / "agents.yaml" + path.write_text(content, encoding="utf-8") + + with pytest.raises(AgentRegistryError, match="agents registry must contain a non-empty agents list"): + load_agent_registry(path) + + +@pytest.mark.parametrize( + "content, expected", + [ + ( + "agents:\n" + " - label: Analyst\n", + "each agent entry requires id and label", + ), + ( + "agents:\n" + " - id: agent-1\n", + "each agent entry requires id and label", + ), + ], +) +def test_load_agent_registry_rejects_missing_id_or_label(tmp_path: Path, content: str, expected: str): + path = tmp_path / "agents.yaml" + path.write_text(content, encoding="utf-8") + + with pytest.raises(AgentRegistryError, match=expected): + load_agent_registry(path) + + +def test_load_agent_registry_rejects_invalid_top_level_yaml(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "- id: agent-1\n" + " label: Analyst\n", + encoding="utf-8", + ) + + with pytest.raises(AgentRegistryError, match="agent registry must be a mapping with an agents list"): + load_agent_registry(path) + + +def test_load_agent_registry_rejects_malformed_yaml(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-2\n" + " label: Research\n" + " - [\n", + encoding="utf-8", + ) + + with pytest.raises(AgentRegistryError, match="invalid agent registry YAML"): + load_agent_registry(path) diff --git a/uv.lock b/uv.lock index 35c8460..76a9426 100644 --- a/uv.lock +++ b/uv.lock @@ -1154,6 +1154,61 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/15/fe/9a58cb6eec633ff6afae150ca53c16f8cc8b65862ccb3d088051efdfceb7/python_socks-2.8.1-py3-none-any.whl", hash = "sha256:28232739c4988064e725cdbcd15be194743dd23f1c910f784163365b9d7be035", size = 55087, upload-time = "2026-02-16T05:23:59.147Z" }, ] +[[package]] +name = "pyyaml" +version = "6.0.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/6d/16/a95b6757765b7b031c9374925bb718d55e0a9ba8a1b6a12d25962ea44347/pyyaml-6.0.3-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:44edc647873928551a01e7a563d7452ccdebee747728c1080d881d68af7b997e", size = 185826, upload-time = "2025-09-25T21:31:58.655Z" }, + { url = "https://files.pythonhosted.org/packages/16/19/13de8e4377ed53079ee996e1ab0a9c33ec2faf808a4647b7b4c0d46dd239/pyyaml-6.0.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:652cb6edd41e718550aad172851962662ff2681490a8a711af6a4d288dd96824", size = 175577, upload-time = "2025-09-25T21:32:00.088Z" }, + { url = "https://files.pythonhosted.org/packages/0c/62/d2eb46264d4b157dae1275b573017abec435397aa59cbcdab6fc978a8af4/pyyaml-6.0.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:10892704fc220243f5305762e276552a0395f7beb4dbf9b14ec8fd43b57f126c", size = 775556, upload-time = "2025-09-25T21:32:01.31Z" }, + { url = "https://files.pythonhosted.org/packages/10/cb/16c3f2cf3266edd25aaa00d6c4350381c8b012ed6f5276675b9eba8d9ff4/pyyaml-6.0.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:850774a7879607d3a6f50d36d04f00ee69e7fc816450e5f7e58d7f17f1ae5c00", size = 882114, upload-time = "2025-09-25T21:32:03.376Z" }, + { url = "https://files.pythonhosted.org/packages/71/60/917329f640924b18ff085ab889a11c763e0b573da888e8404ff486657602/pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b8bb0864c5a28024fac8a632c443c87c5aa6f215c0b126c449ae1a150412f31d", size = 806638, upload-time = "2025-09-25T21:32:04.553Z" }, + { url = "https://files.pythonhosted.org/packages/dd/6f/529b0f316a9fd167281a6c3826b5583e6192dba792dd55e3203d3f8e655a/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1d37d57ad971609cf3c53ba6a7e365e40660e3be0e5175fa9f2365a379d6095a", size = 767463, upload-time = "2025-09-25T21:32:06.152Z" }, + { url = "https://files.pythonhosted.org/packages/f2/6a/b627b4e0c1dd03718543519ffb2f1deea4a1e6d42fbab8021936a4d22589/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:37503bfbfc9d2c40b344d06b2199cf0e96e97957ab1c1b546fd4f87e53e5d3e4", size = 794986, upload-time = "2025-09-25T21:32:07.367Z" }, + { url = "https://files.pythonhosted.org/packages/45/91/47a6e1c42d9ee337c4839208f30d9f09caa9f720ec7582917b264defc875/pyyaml-6.0.3-cp311-cp311-win32.whl", hash = "sha256:8098f252adfa6c80ab48096053f512f2321f0b998f98150cea9bd23d83e1467b", size = 142543, upload-time = "2025-09-25T21:32:08.95Z" }, + { url = "https://files.pythonhosted.org/packages/da/e3/ea007450a105ae919a72393cb06f122f288ef60bba2dc64b26e2646fa315/pyyaml-6.0.3-cp311-cp311-win_amd64.whl", hash = "sha256:9f3bfb4965eb874431221a3ff3fdcddc7e74e3b07799e0e84ca4a0f867d449bf", size = 158763, upload-time = "2025-09-25T21:32:09.96Z" }, + { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" }, + { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" }, + { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" }, + { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" }, + { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" }, + { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" }, + { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" }, + { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" }, + { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" }, + { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" }, + { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" }, + { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" }, + { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" }, + { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" }, + { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" }, + { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" }, + { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" }, + { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" }, + { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" }, + { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, + { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" }, + { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" }, + { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" }, + { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" }, + { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" }, + { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" }, + { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" }, + { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" }, + { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" }, + { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" }, + { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" }, + { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" }, + { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" }, + { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" }, + { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" }, + { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" }, + { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" }, + { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" }, +] + [[package]] name = "referencing" version = "0.37.0" @@ -1321,6 +1376,7 @@ dependencies = [ { name = "matrix-nio" }, { name = "pydantic" }, { name = "python-dotenv" }, + { name = "pyyaml" }, { name = "structlog" }, ] @@ -1347,6 +1403,7 @@ requires-dist = [ { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.23" }, { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.1" }, { name = "python-dotenv", specifier = ">=1.0" }, + { name = "pyyaml", specifier = ">=6.0" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.3" }, { name = "structlog", specifier = ">=24.1" }, ] From 2fb6c10a5a436b08338021ed14084911568fd60b Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:05:26 +0300 Subject: [PATCH 09/55] Reject null agent registry fields --- adapter/matrix/agent_registry.py | 16 ++++++++++++---- tests/adapter/matrix/test_agent_registry.py | 19 +++++++++++++++++++ 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index 5bb99d1..1b03d77 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -29,6 +29,16 @@ class AgentRegistry: raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc +def _required_text(entry: Mapping[str, object], key: str) -> str: + value = entry.get(key) + if value is None: + raise AgentRegistryError("each agent entry requires id and label") + text = str(value).strip() + if not text: + raise AgentRegistryError("each agent entry requires id and label") + return text + + def _load_registry_data(path: str | Path) -> dict[str, object]: try: raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) @@ -52,10 +62,8 @@ def load_agent_registry(path: str | Path) -> AgentRegistry: for entry in entries: if not isinstance(entry, Mapping): raise AgentRegistryError("each agent entry requires id and label") - agent_id = str(entry.get("id", "")).strip() - label = str(entry.get("label", "")).strip() - if not agent_id or not label: - raise AgentRegistryError("each agent entry requires id and label") + agent_id = _required_text(entry, "id") + label = _required_text(entry, "label") if agent_id in seen: raise AgentRegistryError(f"duplicate agent id: {agent_id}") seen.add(agent_id) diff --git a/tests/adapter/matrix/test_agent_registry.py b/tests/adapter/matrix/test_agent_registry.py index 29dd4c5..ce467cc 100644 --- a/tests/adapter/matrix/test_agent_registry.py +++ b/tests/adapter/matrix/test_agent_registry.py @@ -117,3 +117,22 @@ def test_load_agent_registry_rejects_malformed_yaml(tmp_path: Path): with pytest.raises(AgentRegistryError, match="invalid agent registry YAML"): load_agent_registry(path) + + +@pytest.mark.parametrize( + "content", + [ + "agents:\n" + " - id: null\n" + " label: Analyst\n", + "agents:\n" + " - id: agent-1\n" + " label: null\n", + ], +) +def test_load_agent_registry_rejects_null_id_or_label(tmp_path: Path, content: str): + path = tmp_path / "agents.yaml" + path.write_text(content, encoding="utf-8") + + with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): + load_agent_registry(path) From 25aa5d9313e993852663472b05eff89afbeab3e7 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:08:25 +0300 Subject: [PATCH 10/55] Make Matrix agent registry immutable --- adapter/matrix/agent_registry.py | 4 +-- tests/adapter/matrix/test_agent_registry.py | 36 +++++++++++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index 1b03d77..28bfbed 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -19,8 +19,8 @@ class AgentDefinition: class AgentRegistry: def __init__(self, agents: list[AgentDefinition]) -> None: - self.agents = agents - self._by_id = {agent.agent_id: agent for agent in agents} + self.agents = tuple(agents) + self._by_id = {agent.agent_id: agent for agent in self.agents} def get(self, agent_id: str) -> AgentDefinition: try: diff --git a/tests/adapter/matrix/test_agent_registry.py b/tests/adapter/matrix/test_agent_registry.py index ce467cc..e48a4a5 100644 --- a/tests/adapter/matrix/test_agent_registry.py +++ b/tests/adapter/matrix/test_agent_registry.py @@ -22,6 +22,23 @@ def test_load_agent_registry_reads_yaml_entries(tmp_path: Path): assert registry.get("agent-1").label == "Analyst" +def test_agent_registry_agents_sequence_is_immutable(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n", + encoding="utf-8", + ) + + registry = load_agent_registry(path) + + with pytest.raises(AttributeError): + registry.agents.append( # type: ignore[attr-defined] + registry.agents[0] + ) + + def test_load_agent_registry_rejects_duplicate_ids(tmp_path: Path): path = tmp_path / "agents.yaml" path.write_text( @@ -136,3 +153,22 @@ def test_load_agent_registry_rejects_null_id_or_label(tmp_path: Path, content: s with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): load_agent_registry(path) + + +@pytest.mark.parametrize( + "content", + [ + "agents:\n" + " - id: ' '\n" + " label: Analyst\n", + "agents:\n" + " - id: agent-1\n" + " label: ' '\n", + ], +) +def test_load_agent_registry_rejects_blank_id_or_label(tmp_path: Path, content: str): + path = tmp_path / "agents.yaml" + path.write_text(content, encoding="utf-8") + + with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): + load_agent_registry(path) From 3b0401fb7c2b97a588d1197df7453b3183c878d6 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:11:02 +0300 Subject: [PATCH 11/55] Require string agent registry fields --- adapter/matrix/agent_registry.py | 4 ++-- tests/adapter/matrix/test_agent_registry.py | 25 +++++++++++++++++++++ 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index 28bfbed..bac84a9 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -31,9 +31,9 @@ class AgentRegistry: def _required_text(entry: Mapping[str, object], key: str) -> str: value = entry.get(key) - if value is None: + if not isinstance(value, str): raise AgentRegistryError("each agent entry requires id and label") - text = str(value).strip() + text = value.strip() if not text: raise AgentRegistryError("each agent entry requires id and label") return text diff --git a/tests/adapter/matrix/test_agent_registry.py b/tests/adapter/matrix/test_agent_registry.py index e48a4a5..a918f84 100644 --- a/tests/adapter/matrix/test_agent_registry.py +++ b/tests/adapter/matrix/test_agent_registry.py @@ -172,3 +172,28 @@ def test_load_agent_registry_rejects_blank_id_or_label(tmp_path: Path, content: with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): load_agent_registry(path) + + +@pytest.mark.parametrize( + "content", + [ + "agents:\n" + " - id: 123\n" + " label: Analyst\n", + "agents:\n" + " - id: agent-1\n" + " label: 456\n", + "agents:\n" + " - id: true\n" + " label: Analyst\n", + "agents:\n" + " - id: agent-1\n" + " label: false\n", + ], +) +def test_load_agent_registry_rejects_non_string_id_or_label(tmp_path: Path, content: str): + path = tmp_path / "agents.yaml" + path.write_text(content, encoding="utf-8") + + with pytest.raises(AgentRegistryError, match="each agent entry requires id and label"): + load_agent_registry(path) From 98caca100cd0654df621c33f1d02e2cc7872ad87 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:12:29 +0300 Subject: [PATCH 12/55] Clarify Matrix agent registry docs --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4a50e2c..faa9d65 100644 --- a/README.md +++ b/README.md @@ -135,8 +135,8 @@ PROVIDER_API_KEY=... ### 3. Registry агентов 1. Скопируй `config/matrix-agents.example.yaml` в `config/matrix-agents.yaml` -2. Укажи `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` -3. Этот registry нужен для будущего выбора upstream-агента; сам командный переключатель `!agent` в текущем коде ещё не реализован +2. При необходимости укажи `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` в `.env` как подготовку к будущему multi-agent routing +3. Этот registry сейчас является конфигурационным артефактом Task 1; текущий Matrix runtime его ещё не читает ### 4. Compose runtime From 7627012f2412e50196403d769241cff71d289f92 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:14:52 +0300 Subject: [PATCH 13/55] Keep Matrix registry docs preparatory --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index faa9d65..24f6c36 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,6 @@ MATRIX_PASSWORD=... # или MATRIX_ACCESS_TOKEN=... # Выбор backend: mock (по умолчанию) или real (подключение к platform-agent) MATRIX_PLATFORM_BACKEND=real -MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml # compose runtime: platform-agent service name + shared /workspace AGENT_BASE_URL=http://platform-agent:8000 @@ -135,7 +134,7 @@ PROVIDER_API_KEY=... ### 3. Registry агентов 1. Скопируй `config/matrix-agents.example.yaml` в `config/matrix-agents.yaml` -2. При необходимости укажи `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` в `.env` как подготовку к будущему multi-agent routing +2. Если готовишься к multi-agent routing, добавь `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` в `.env` 3. Этот registry сейчас является конфигурационным артефактом Task 1; текущий Matrix runtime его ещё не читает ### 4. Compose runtime From 242f4aadd34ca62bcd5a14bd3999b08cc47cadb2 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:22:05 +0300 Subject: [PATCH 14/55] feat: add matrix routed platform facade --- adapter/matrix/bot.py | 34 ++- adapter/matrix/routed_platform.py | 110 +++++++++ tests/adapter/matrix/test_routed_platform.py | 240 +++++++++++++++++++ 3 files changed, 376 insertions(+), 8 deletions(-) create mode 100644 adapter/matrix/routed_platform.py create mode 100644 tests/adapter/matrix/test_routed_platform.py diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index debd2fa..fc1b57a 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -30,11 +30,13 @@ from adapter.matrix.files import ( matrix_msgtype_for_attachment, resolve_workspace_attachment_path, ) +from adapter.matrix.agent_registry import load_agent_registry from adapter.matrix.handlers import register_matrix_handlers from adapter.matrix.handlers.auth import handle_invite, provision_workspace_chat from adapter.matrix.handlers.context_commands import ( LOAD_PROMPT, ) +from adapter.matrix.routed_platform import RoutedPlatformClient from adapter.matrix.room_router import resolve_chat_id from adapter.matrix.store import ( add_staged_attachment, @@ -118,13 +120,31 @@ def _agent_base_url_from_env() -> str: return "http://127.0.0.1:8000" -def _build_platform_from_env() -> PlatformClient: +def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> PlatformClient: backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower() if backend == "real": + prototype_state = PrototypeStateStore() + registry_path = os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip() + if registry_path: + registry = load_agent_registry(registry_path) + delegates = { + agent.agent_id: RealPlatformClient( + agent_id=agent.agent_id, + agent_base_url=_agent_base_url_from_env(), + prototype_state=prototype_state, + platform="matrix", + ) + for agent in registry.agents + } + return RoutedPlatformClient( + chat_mgr=chat_mgr, + store=store, + delegates=delegates, + ) return RealPlatformClient( agent_id="matrix-bot", agent_base_url=_agent_base_url_from_env(), - prototype_state=PrototypeStateStore(), + prototype_state=prototype_state, platform="matrix", ) return MockPlatformClient() @@ -135,9 +155,10 @@ def build_runtime( store: StateStore | None = None, client: AsyncClient | None = None, ) -> MatrixRuntime: - platform = platform or _build_platform_from_env() store = store or InMemoryStore() chat_mgr = ChatManager(platform, store) + platform = platform or _build_platform_from_env(store=store, chat_mgr=chat_mgr) + chat_mgr = ChatManager(platform, store) auth_mgr = AuthManager(platform, store) settings_mgr = SettingsManager(platform, store) prototype_state = getattr(platform, "_prototype_state", None) @@ -224,10 +245,7 @@ class MatrixBot: ) return local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender) - dispatch_chat_id = local_chat_id - if not body.startswith("!"): - dispatch_chat_id = (room_meta or {}).get("platform_chat_id") or local_chat_id - incoming = from_room_event(event, room_id=room.room_id, chat_id=dispatch_chat_id) + incoming = from_room_event(event, room_id=room.room_id, chat_id=local_chat_id) if incoming is None: return if isinstance(incoming, IncomingCommand) and incoming.command in { @@ -274,7 +292,7 @@ class MatrixBot: ) outgoing = [ OutgoingMessage( - chat_id=dispatch_chat_id, + chat_id=local_chat_id, text="Сервис временно недоступен. Попробуйте ещё раз позже.", ) ] diff --git a/adapter/matrix/routed_platform.py b/adapter/matrix/routed_platform.py new file mode 100644 index 0000000..8f505e5 --- /dev/null +++ b/adapter/matrix/routed_platform.py @@ -0,0 +1,110 @@ +from __future__ import annotations + +from collections.abc import AsyncIterator, Mapping + +from adapter.matrix.store import get_room_meta +from core.chat import ChatManager +from core.store import StateStore +from sdk.interface import ( + Attachment, + MessageChunk, + MessageResponse, + PlatformClient, + PlatformError, + User, + UserSettings, +) + + +class RoutedPlatformClient(PlatformClient): + def __init__( + self, + *, + chat_mgr: ChatManager, + store: StateStore, + delegates: Mapping[str, PlatformClient], + ) -> None: + if not delegates: + raise ValueError("RoutedPlatformClient requires at least one delegate") + self._chat_mgr = chat_mgr + self._store = store + self._delegates = dict(delegates) + self._default_client = next(iter(self._delegates.values())) + self._prototype_state = getattr(self._default_client, "_prototype_state", None) + + async def get_or_create_user( + self, + external_id: str, + platform: str, + display_name: str | None = None, + ) -> User: + return await self._default_client.get_or_create_user( + external_id=external_id, + platform=platform, + display_name=display_name, + ) + + async def send_message( + self, + user_id: str, + chat_id: str, + text: str, + attachments: list[Attachment] | None = None, + ) -> MessageResponse: + delegate, platform_chat_id = await self._resolve_delegate(user_id, chat_id) + return await delegate.send_message(user_id, platform_chat_id, text, attachments) + + async def stream_message( + self, + user_id: str, + chat_id: str, + text: str, + attachments: list[Attachment] | None = None, + ) -> AsyncIterator[MessageChunk]: + delegate, platform_chat_id = await self._resolve_delegate(user_id, chat_id) + async for chunk in delegate.stream_message(user_id, platform_chat_id, text, attachments): + yield chunk + + async def get_settings(self, user_id: str) -> UserSettings: + return await self._default_client.get_settings(user_id) + + async def update_settings(self, user_id: str, action) -> None: + await self._default_client.update_settings(user_id, action) + + async def close(self) -> None: + for delegate in self._delegates.values(): + close = getattr(delegate, "close", None) + if callable(close): + await close() + + async def _resolve_delegate(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]: + chat = await self._chat_mgr.get(local_chat_id, user_id) + if chat is None: + raise PlatformError( + f"unknown matrix chat id: {local_chat_id}", + code="MATRIX_CHAT_NOT_FOUND", + ) + + room_meta = await get_room_meta(self._store, chat.surface_ref) + if room_meta is None: + raise PlatformError( + f"matrix room is not bound: {chat.surface_ref}", + code="MATRIX_ROOM_NOT_BOUND", + ) + + agent_id = room_meta.get("agent_id") + platform_chat_id = room_meta.get("platform_chat_id") + if not agent_id or not platform_chat_id: + raise PlatformError( + f"matrix room routing is incomplete: {chat.surface_ref}", + code="MATRIX_ROUTE_INCOMPLETE", + ) + + delegate = self._delegates.get(str(agent_id)) + if delegate is None: + raise PlatformError( + f"unknown matrix agent id: {agent_id}", + code="MATRIX_AGENT_NOT_FOUND", + ) + + return delegate, str(platform_chat_id) diff --git a/tests/adapter/matrix/test_routed_platform.py b/tests/adapter/matrix/test_routed_platform.py new file mode 100644 index 0000000..fc2f89d --- /dev/null +++ b/tests/adapter/matrix/test_routed_platform.py @@ -0,0 +1,240 @@ +from __future__ import annotations + +from collections.abc import AsyncIterator +from pathlib import Path +from types import SimpleNamespace +from unittest.mock import AsyncMock + +import pytest + +from adapter.matrix.bot import MatrixBot, build_runtime +from adapter.matrix.routed_platform import RoutedPlatformClient +from adapter.matrix.store import set_room_meta +from core.chat import ChatManager +from core.store import InMemoryStore +from sdk.interface import MessageChunk, MessageResponse, User, UserSettings +from sdk.mock import MockPlatformClient + + +class FakeDelegate: + def __init__(self, *, name: str) -> None: + self.name = name + self.send_calls: list[dict] = [] + self.stream_calls: list[dict] = [] + self.user_calls: list[dict] = [] + self.settings_calls: list[str] = [] + self.update_calls: list[tuple[str, object]] = [] + + async def get_or_create_user( + self, + external_id: str, + platform: str, + display_name: str | None = None, + ) -> User: + self.user_calls.append( + { + "external_id": external_id, + "platform": platform, + "display_name": display_name, + } + ) + return User( + user_id=f"user-{self.name}", + external_id=external_id, + platform=platform, + display_name=display_name, + created_at="2025-01-01T00:00:00Z", + is_new=False, + ) + + async def send_message( + self, + user_id: str, + chat_id: str, + text: str, + attachments=None, + ) -> MessageResponse: + self.send_calls.append( + { + "user_id": user_id, + "chat_id": chat_id, + "text": text, + "attachments": attachments, + } + ) + return MessageResponse( + message_id=f"msg-{self.name}", + response=f"reply-{self.name}", + tokens_used=0, + finished=True, + ) + + async def stream_message( + self, + user_id: str, + chat_id: str, + text: str, + attachments=None, + ) -> AsyncIterator[MessageChunk]: + self.stream_calls.append( + { + "user_id": user_id, + "chat_id": chat_id, + "text": text, + "attachments": attachments, + } + ) + yield MessageChunk( + message_id=f"stream-{self.name}", + delta=f"delta-{self.name}", + finished=True, + tokens_used=0, + ) + + async def get_settings(self, user_id: str) -> UserSettings: + self.settings_calls.append(user_id) + return UserSettings(skills={"files": True}) + + async def update_settings(self, user_id: str, action: object) -> None: + self.update_calls.append((user_id, action)) + + +@pytest.mark.asyncio +async def test_send_message_routes_by_room_agent_and_platform_chat_id(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org") + await set_room_meta( + store, + "!room:example.org", + {"platform_chat_id": "41", "agent_id": "agent-2"}, + ) + delegates = { + "agent-1": FakeDelegate(name="agent-1"), + "agent-2": FakeDelegate(name="agent-2"), + } + platform = RoutedPlatformClient(chat_mgr=chat_mgr, store=store, delegates=delegates) + + response = await platform.send_message("u1", "C1", "hello", attachments=[]) + + assert response.response == "reply-agent-2" + assert delegates["agent-1"].send_calls == [] + assert delegates["agent-2"].send_calls == [ + { + "user_id": "u1", + "chat_id": "41", + "text": "hello", + "attachments": [], + } + ] + + +@pytest.mark.asyncio +async def test_stream_message_routes_by_room_agent_and_platform_chat_id(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org") + await set_room_meta( + store, + "!room:example.org", + {"platform_chat_id": "41", "agent_id": "agent-2"}, + ) + delegates = { + "agent-1": FakeDelegate(name="agent-1"), + "agent-2": FakeDelegate(name="agent-2"), + } + platform = RoutedPlatformClient(chat_mgr=chat_mgr, store=store, delegates=delegates) + + chunks = [chunk async for chunk in platform.stream_message("u1", "C1", "hello")] + + assert [chunk.delta for chunk in chunks] == ["delta-agent-2"] + assert delegates["agent-1"].stream_calls == [] + assert delegates["agent-2"].stream_calls == [ + { + "user_id": "u1", + "chat_id": "41", + "text": "hello", + "attachments": None, + } + ] + + +@pytest.mark.asyncio +async def test_user_and_settings_delegate_to_default_client(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + delegates = { + "agent-1": FakeDelegate(name="agent-1"), + "agent-2": FakeDelegate(name="agent-2"), + } + platform = RoutedPlatformClient(chat_mgr=chat_mgr, store=store, delegates=delegates) + + user = await platform.get_or_create_user("ext-1", "matrix", display_name="Alice") + settings = await platform.get_settings("u1") + await platform.update_settings("u1", {"action": "noop"}) + + assert user.user_id == "user-agent-1" + assert settings.skills == {"files": True} + assert delegates["agent-1"].user_calls == [ + { + "external_id": "ext-1", + "platform": "matrix", + "display_name": "Alice", + } + ] + assert delegates["agent-2"].user_calls == [] + assert delegates["agent-1"].settings_calls == ["u1"] + assert delegates["agent-1"].update_calls == [("u1", {"action": "noop"})] + + +@pytest.mark.asyncio +async def test_build_runtime_real_backend_uses_routed_platform_with_registry( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +): + registry_path = tmp_path / "matrix-agents.yaml" + registry_path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-2\n" + " label: Research\n", + encoding="utf-8", + ) + monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real") + monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path)) + monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example") + + runtime = build_runtime() + + assert isinstance(runtime.platform, RoutedPlatformClient) + assert set(runtime.platform._delegates) == {"agent-1", "agent-2"} + assert runtime.platform._delegates["agent-1"].agent_base_url == "http://agent.example" + assert runtime.platform._delegates["agent-1"].agent_id == "agent-1" + assert runtime.platform._delegates["agent-2"].agent_id == "agent-2" + + +@pytest.mark.asyncio +async def test_bot_keeps_local_chat_id_for_plain_message_dispatch(): + runtime = build_runtime(platform=MockPlatformClient()) + await set_room_meta( + runtime.store, + "!chat1:example.org", + { + "chat_id": "C1", + "matrix_user_id": "@alice:example.org", + "platform_chat_id": "41", + "agent_id": "agent-2", + }, + ) + runtime.dispatcher.dispatch = AsyncMock(return_value=[]) + bot = MatrixBot(SimpleNamespace(user_id="@bot:example.org"), runtime) + + await bot.on_room_message( + SimpleNamespace(room_id="!chat1:example.org"), + SimpleNamespace(sender="@alice:example.org", body="hello"), + ) + + dispatched = runtime.dispatcher.dispatch.await_args.args[0] + assert dispatched.chat_id == "C1" + assert dispatched.text == "hello" From 9ccba161a2498e41f99217a095c81ae3b2485189 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:24:56 +0300 Subject: [PATCH 15/55] fix: require matrix agent registry in real mode --- adapter/matrix/bot.py | 42 ++++++++++---------- tests/adapter/matrix/test_routed_platform.py | 22 ++++++++++ 2 files changed, 43 insertions(+), 21 deletions(-) diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index fc1b57a..636d6ef 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -30,7 +30,7 @@ from adapter.matrix.files import ( matrix_msgtype_for_attachment, resolve_workspace_attachment_path, ) -from adapter.matrix.agent_registry import load_agent_registry +from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry from adapter.matrix.handlers import register_matrix_handlers from adapter.matrix.handlers.auth import handle_invite, provision_workspace_chat from adapter.matrix.handlers.context_commands import ( @@ -125,27 +125,27 @@ def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> Pla if backend == "real": prototype_state = PrototypeStateStore() registry_path = os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip() - if registry_path: - registry = load_agent_registry(registry_path) - delegates = { - agent.agent_id: RealPlatformClient( - agent_id=agent.agent_id, - agent_base_url=_agent_base_url_from_env(), - prototype_state=prototype_state, - platform="matrix", - ) - for agent in registry.agents - } - return RoutedPlatformClient( - chat_mgr=chat_mgr, - store=store, - delegates=delegates, + if not registry_path: + raise RuntimeError( + "MATRIX_AGENT_REGISTRY_PATH is required when MATRIX_PLATFORM_BACKEND=real" ) - return RealPlatformClient( - agent_id="matrix-bot", - agent_base_url=_agent_base_url_from_env(), - prototype_state=prototype_state, - platform="matrix", + try: + registry = load_agent_registry(registry_path) + except (AgentRegistryError, OSError) as exc: + raise RuntimeError(f"failed to load matrix agent registry: {registry_path}") from exc + delegates = { + agent.agent_id: RealPlatformClient( + agent_id=agent.agent_id, + agent_base_url=_agent_base_url_from_env(), + prototype_state=prototype_state, + platform="matrix", + ) + for agent in registry.agents + } + return RoutedPlatformClient( + chat_mgr=chat_mgr, + store=store, + delegates=delegates, ) return MockPlatformClient() diff --git a/tests/adapter/matrix/test_routed_platform.py b/tests/adapter/matrix/test_routed_platform.py index fc2f89d..1aa3400 100644 --- a/tests/adapter/matrix/test_routed_platform.py +++ b/tests/adapter/matrix/test_routed_platform.py @@ -214,6 +214,28 @@ async def test_build_runtime_real_backend_uses_routed_platform_with_registry( assert runtime.platform._delegates["agent-2"].agent_id == "agent-2" +def test_build_runtime_real_backend_requires_registry_path(monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real") + monkeypatch.delenv("MATRIX_AGENT_REGISTRY_PATH", raising=False) + monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example") + + with pytest.raises(RuntimeError, match="MATRIX_AGENT_REGISTRY_PATH"): + build_runtime() + + +def test_build_runtime_real_backend_fails_explicitly_on_invalid_registry( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +): + registry_path = tmp_path / "missing.yaml" + monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real") + monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path)) + monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example") + + with pytest.raises(RuntimeError, match="failed to load matrix agent registry"): + build_runtime() + + @pytest.mark.asyncio async def test_bot_keeps_local_chat_id_for_plain_message_dispatch(): runtime = build_runtime(platform=MockPlatformClient()) From a65227e490c97a1e97acb9d7b070cfd4cae85c45 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:29:49 +0300 Subject: [PATCH 16/55] test: align matrix dispatch chat id contract --- tests/adapter/matrix/test_dispatcher.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/adapter/matrix/test_dispatcher.py b/tests/adapter/matrix/test_dispatcher.py index 7fa7a47..f338495 100644 --- a/tests/adapter/matrix/test_dispatcher.py +++ b/tests/adapter/matrix/test_dispatcher.py @@ -276,7 +276,7 @@ async def test_bot_assigns_platform_chat_id_for_existing_managed_room(): runtime.dispatcher.dispatch.assert_awaited_once() -async def test_bot_routes_plain_messages_via_platform_chat_id(): +async def test_bot_keeps_local_chat_id_for_plain_messages(): runtime = build_runtime(platform=MockPlatformClient()) await set_room_meta( runtime.store, @@ -297,7 +297,7 @@ async def test_bot_routes_plain_messages_via_platform_chat_id(): await bot.on_room_message(room, event) dispatched = runtime.dispatcher.dispatch.await_args.args[0] - assert dispatched.chat_id == "41" + assert dispatched.chat_id == "C1" assert dispatched.text == "hello" From 74cf028e8f903a756e3918aca4734f23f227aac7 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 13:54:25 +0300 Subject: [PATCH 17/55] feat: add !agent command and durable user agent selection Users can now list available agents with !agent and select one by number. Selection persists in user metadata (selected_agent_id). If the current room has no agent binding yet, selecting an agent binds it immediately so the user can start messaging without !new. Also updates the dispatcher test to reflect that real-mode platform is now RoutedPlatformClient, not a bare RealPlatformClient. --- adapter/matrix/handlers/__init__.py | 4 + adapter/matrix/handlers/agent.py | 78 +++++++++ adapter/matrix/handlers/settings.py | 3 + adapter/matrix/store.py | 21 +++ pyproject.toml | 2 +- tests/adapter/matrix/test_agent_handler.py | 175 +++++++++++++++++++++ tests/adapter/matrix/test_dispatcher.py | 15 +- 7 files changed, 292 insertions(+), 6 deletions(-) create mode 100644 adapter/matrix/handlers/agent.py create mode 100644 tests/adapter/matrix/test_agent_handler.py diff --git a/adapter/matrix/handlers/__init__.py b/adapter/matrix/handlers/__init__.py index c028735..7484a37 100644 --- a/adapter/matrix/handlers/__init__.py +++ b/adapter/matrix/handlers/__init__.py @@ -1,5 +1,6 @@ from __future__ import annotations +from adapter.matrix.handlers.agent import make_handle_agent from adapter.matrix.handlers.chat import ( handle_list_chats, make_handle_archive, @@ -34,9 +35,12 @@ def register_matrix_handlers( dispatcher: EventDispatcher, client=None, store=None, + registry=None, prototype_state=None, agent_base_url: str = "http://127.0.0.1:8000", ) -> None: + if store is not None and registry is not None: + dispatcher.register(IncomingCommand, "agent", make_handle_agent(store, registry)) dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store)) dispatcher.register(IncomingCommand, "chats", handle_list_chats) dispatcher.register(IncomingCommand, "rename", make_handle_rename(client, store)) diff --git a/adapter/matrix/handlers/agent.py b/adapter/matrix/handlers/agent.py new file mode 100644 index 0000000..f9bf804 --- /dev/null +++ b/adapter/matrix/handlers/agent.py @@ -0,0 +1,78 @@ +from __future__ import annotations + +from collections.abc import Awaitable, Callable + +from adapter.matrix.agent_registry import AgentRegistry +from adapter.matrix.store import ( + get_platform_chat_id, + get_selected_agent_id, + get_room_meta, + next_platform_chat_id, + set_platform_chat_id, + set_room_agent_id, + set_selected_agent_id, +) +from core.protocol import IncomingCommand, OutgoingMessage + + +def make_handle_agent(store, registry: AgentRegistry) -> Callable[..., Awaitable[list]]: + async def handle_agent( + event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr + ) -> list: + if not event.args: + selected_agent_id = await get_selected_agent_id(store, event.user_id) + lines = ["Доступные агенты:"] + for index, agent in enumerate(registry.agents, start=1): + suffix = " [текущий]" if agent.agent_id == selected_agent_id else "" + lines.append(f"{index}. {agent.label}{suffix}") + lines.extend(["", "Выбери агент: !agent <номер>"]) + return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))] + + try: + selected_index = int(event.args[0]) + except ValueError: + return [ + OutgoingMessage( + chat_id=event.chat_id, + text="Укажи номер агента из списка: !agent <номер>.", + ) + ] + + if selected_index < 1 or selected_index > len(registry.agents): + return [ + OutgoingMessage( + chat_id=event.chat_id, + text="Такого агента нет. Открой список через !agent.", + ) + ] + + agent = registry.agents[selected_index - 1] + await set_selected_agent_id(store, event.user_id, agent.agent_id) + + current_chat = await chat_mgr.get(event.chat_id, user_id=event.user_id) + if current_chat is not None and current_chat.surface_ref: + room_id = current_chat.surface_ref + room_meta = await get_room_meta(store, room_id) + if room_meta is not None and not room_meta.get("agent_id"): + await set_room_agent_id(store, room_id, agent.agent_id) + if await get_platform_chat_id(store, room_id) is None: + await set_platform_chat_id( + store, + room_id, + await next_platform_chat_id(store), + ) + return [ + OutgoingMessage( + chat_id=event.chat_id, + text=f"Агент {agent.label} выбран. Текущий чат готов к работе.", + ) + ] + + return [ + OutgoingMessage( + chat_id=event.chat_id, + text=f"Агент переключен на {agent.label}. Продолжай через !new.", + ) + ] + + return handle_agent diff --git a/adapter/matrix/handlers/settings.py b/adapter/matrix/handlers/settings.py index 07e64c0..e6a740c 100644 --- a/adapter/matrix/handlers/settings.py +++ b/adapter/matrix/handlers/settings.py @@ -14,6 +14,9 @@ HELP_TEXT = "\n".join( "!save [имя] сохранить текущий контекст", "!load показать сохранённые контексты", "", + "!agent показать доступных агентов", + "!agent <номер> выбрать агента для следующих чатов", + "", "Остальные команды и настройки скрыты в MVP, чтобы не вводить в заблуждение.", ] ) diff --git a/adapter/matrix/store.py b/adapter/matrix/store.py index e835ace..b78d4b5 100644 --- a/adapter/matrix/store.py +++ b/adapter/matrix/store.py @@ -45,6 +45,27 @@ async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> N await store.set(f"{USER_META_PREFIX}{matrix_user_id}", meta) +async def get_selected_agent_id(store: StateStore, matrix_user_id: str) -> str | None: + meta = await get_user_meta(store, matrix_user_id) + return meta.get("selected_agent_id") if meta else None + + +async def set_selected_agent_id( + store: StateStore, + matrix_user_id: str, + agent_id: str, +) -> None: + meta = dict(await get_user_meta(store, matrix_user_id) or {}) + meta["selected_agent_id"] = agent_id + await set_user_meta(store, matrix_user_id, meta) + + +async def set_room_agent_id(store: StateStore, room_id: str, agent_id: str) -> None: + meta = dict(await get_room_meta(store, room_id) or {}) + meta["agent_id"] = agent_id + await set_room_meta(store, room_id, meta) + + async def get_room_state(store: StateStore, room_id: str) -> str: data = await store.get(f"{ROOM_STATE_PREFIX}{room_id}") return data["state"] if data else "idle" diff --git a/pyproject.toml b/pyproject.toml index f2fc338..73dfbd7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,7 +16,7 @@ dependencies = [ "python-dotenv>=1.0", "httpx>=0.27", "aiohttp>=3.9", - "PyYAML>=6.0", + "pyyaml>=6.0", ] [project.optional-dependencies] diff --git a/tests/adapter/matrix/test_agent_handler.py b/tests/adapter/matrix/test_agent_handler.py new file mode 100644 index 0000000..dd101a1 --- /dev/null +++ b/tests/adapter/matrix/test_agent_handler.py @@ -0,0 +1,175 @@ +from __future__ import annotations + +from pathlib import Path + +import pytest + +from adapter.matrix.bot import build_runtime +from adapter.matrix.agent_registry import AgentDefinition, AgentRegistry +from adapter.matrix.handlers.agent import make_handle_agent +from adapter.matrix.store import get_room_meta, get_selected_agent_id, set_selected_agent_id, set_room_meta +from core.chat import ChatManager +from core.protocol import IncomingCommand, OutgoingMessage +from core.settings import SettingsManager +from core.store import InMemoryStore +from sdk.mock import MockPlatformClient + + +def _registry() -> AgentRegistry: + return AgentRegistry( + [ + AgentDefinition(agent_id="agent-1", label="Analyst"), + AgentDefinition(agent_id="agent-2", label="Research"), + ] + ) + + +async def test_agent_command_lists_available_agents_with_selected_marker(): + store = InMemoryStore() + await set_selected_agent_id(store, "@alice:example.org", "agent-2") + handler = make_handle_agent(store, _registry()) + + result = await handler( + event=IncomingCommand( + user_id="@alice:example.org", + platform="matrix", + chat_id="C1", + command="agent", + ), + auth_mgr=None, + platform=MockPlatformClient(), + chat_mgr=ChatManager(None, store), + settings_mgr=SettingsManager(MockPlatformClient(), store), + ) + + assert result == [ + OutgoingMessage( + chat_id="C1", + text=( + "Доступные агенты:\n" + "1. Analyst\n" + "2. Research [текущий]\n" + "\n" + "Выбери агент: !agent <номер>" + ), + ) + ] + + +async def test_agent_command_persists_selected_agent_id(): + store = InMemoryStore() + handler = make_handle_agent(store, _registry()) + + result = await handler( + event=IncomingCommand( + user_id="@alice:example.org", + platform="matrix", + chat_id="C1", + command="agent", + args=["2"], + ), + auth_mgr=None, + platform=MockPlatformClient(), + chat_mgr=ChatManager(None, store), + settings_mgr=SettingsManager(MockPlatformClient(), store), + ) + + assert await get_selected_agent_id(store, "@alice:example.org") == "agent-2" + assert result == [ + OutgoingMessage( + chat_id="C1", + text="Агент переключен на Research. Продолжай через !new.", + ) + ] + + +async def test_agent_command_binds_existing_unbound_room_to_selected_agent(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create( + user_id="@alice:example.org", + chat_id="C1", + platform="matrix", + surface_ref="!room:example.org", + name="Research", + ) + await set_room_meta( + store, + "!room:example.org", + { + "chat_id": "C1", + "matrix_user_id": "@alice:example.org", + "display_name": "Research", + }, + ) + handler = make_handle_agent(store, _registry()) + + result = await handler( + event=IncomingCommand( + user_id="@alice:example.org", + platform="matrix", + chat_id="C1", + command="agent", + args=["1"], + ), + auth_mgr=None, + platform=MockPlatformClient(), + chat_mgr=chat_mgr, + settings_mgr=SettingsManager(MockPlatformClient(), store), + ) + + assert await get_selected_agent_id(store, "@alice:example.org") == "agent-1" + assert await get_room_meta(store, "!room:example.org") == { + "chat_id": "C1", + "matrix_user_id": "@alice:example.org", + "display_name": "Research", + "agent_id": "agent-1", + "platform_chat_id": "1", + } + assert result == [ + OutgoingMessage( + chat_id="C1", + text="Агент Analyst выбран. Текущий чат готов к работе.", + ) + ] + + +@pytest.mark.asyncio +async def test_build_runtime_registers_agent_handler_when_registry_is_configured( + monkeypatch: pytest.MonkeyPatch, + tmp_path: Path, +): + registry_path = tmp_path / "matrix-agents.yaml" + registry_path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-2\n" + " label: Research\n", + encoding="utf-8", + ) + monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path)) + + runtime = build_runtime(platform=MockPlatformClient()) + + result = await runtime.dispatcher.dispatch( + IncomingCommand( + user_id="@alice:example.org", + platform="matrix", + chat_id="C1", + command="agent", + ) + ) + + assert result == [ + OutgoingMessage( + chat_id="C1", + text=( + "Доступные агенты:\n" + "1. Analyst\n" + "2. Research\n" + "\n" + "Выбери агент: !agent <номер>" + ), + ) + ] diff --git a/tests/adapter/matrix/test_dispatcher.py b/tests/adapter/matrix/test_dispatcher.py index f338495..f9d8c14 100644 --- a/tests/adapter/matrix/test_dispatcher.py +++ b/tests/adapter/matrix/test_dispatcher.py @@ -36,7 +36,7 @@ from core.protocol import ( ) from sdk.interface import PlatformError from sdk.mock import MockPlatformClient -from sdk.real import RealPlatformClient +from adapter.matrix.routed_platform import RoutedPlatformClient async def test_matrix_dispatcher_registers_custom_handlers(): @@ -907,15 +907,20 @@ async def test_prepare_live_sync_returns_next_batch_from_bootstrap_sync(): assert since == "s123" -async def test_build_runtime_uses_real_platform_when_matrix_backend_is_real(monkeypatch): +async def test_build_runtime_uses_routed_platform_when_matrix_backend_is_real( + monkeypatch, tmp_path +): + registry_path = tmp_path / "agents.yaml" + registry_path.write_text( + "agents:\n - id: agent-1\n label: Analyst\n", encoding="utf-8" + ) monkeypatch.setenv("MATRIX_PLATFORM_BACKEND", "real") monkeypatch.setenv("AGENT_BASE_URL", "http://agent.example") + monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path)) runtime = build_runtime() - assert isinstance(runtime.platform, RealPlatformClient) - assert runtime.platform.agent_base_url == "http://agent.example" - assert runtime.platform.agent_id == "matrix-bot" + assert isinstance(runtime.platform, RoutedPlatformClient) async def test_matrix_main_closes_platform_without_connecting_root_agent(monkeypatch): From e733119d1e67ab438e8a449cea9deff54511f7d5 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 14:01:49 +0300 Subject: [PATCH 18/55] feat: enforce agent routing and persist restart state Task 4: stale room blocking + agent_id binding - MatrixBot._check_agent_routing: blocks normal messages when user has no selected agent or room is bound to a different agent - agent_routing_enabled flag on MatrixRuntime activates the check only in real multi-agent mode (RoutedPlatformClient) - make_handle_new_chat now writes agent_id into new room metadata when user already has a selected agent Task 5: durable restart state tests - test_restart_persistence.py proves selected_agent_id, room agent_id, platform_chat_id, and the sequence counter all survive SQLiteStore close/reopen; also covers clean startup with no prior state --- adapter/matrix/bot.py | 73 ++++++++++-- adapter/matrix/handlers/chat.py | 25 +++-- .../matrix/test_restart_persistence.py | 75 +++++++++++++ .../matrix/test_routing_enforcement.py | 105 ++++++++++++++++++ 4 files changed, 256 insertions(+), 22 deletions(-) create mode 100644 tests/adapter/matrix/test_restart_persistence.py create mode 100644 tests/adapter/matrix/test_routing_enforcement.py diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index 636d6ef..cf8adb1 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -30,7 +30,7 @@ from adapter.matrix.files import ( matrix_msgtype_for_attachment, resolve_workspace_attachment_path, ) -from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry +from adapter.matrix.agent_registry import AgentRegistry, AgentRegistryError, load_agent_registry from adapter.matrix.handlers import register_matrix_handlers from adapter.matrix.handlers.auth import handle_invite, provision_workspace_chat from adapter.matrix.handlers.context_commands import ( @@ -44,11 +44,13 @@ from adapter.matrix.store import ( clear_staged_attachments, get_load_pending, get_room_meta, + get_selected_agent_id, get_staged_attachments, next_platform_chat_id, remove_staged_attachment_at, set_pending_confirm, set_platform_chat_id, + set_room_agent_id, set_room_meta, ) from core.auth import AuthManager @@ -85,6 +87,7 @@ class MatrixRuntime: auth_mgr: AuthManager settings_mgr: SettingsManager dispatcher: EventDispatcher + agent_routing_enabled: bool = False def build_event_dispatcher(platform: PlatformClient, store: StateStore) -> EventDispatcher: @@ -93,6 +96,7 @@ def build_event_dispatcher(platform: PlatformClient, store: StateStore) -> Event settings_mgr = SettingsManager(platform, store) prototype_state = getattr(platform, "_prototype_state", None) agent_base_url = _agent_base_url_from_env() + registry = _load_agent_registry_from_env() dispatcher = EventDispatcher( platform=platform, chat_mgr=chat_mgr, auth_mgr=auth_mgr, settings_mgr=settings_mgr ) @@ -100,6 +104,7 @@ def build_event_dispatcher(platform: PlatformClient, store: StateStore) -> Event register_matrix_handlers( dispatcher, store=store, + registry=registry, prototype_state=prototype_state, agent_base_url=agent_base_url, ) @@ -120,19 +125,26 @@ def _agent_base_url_from_env() -> str: return "http://127.0.0.1:8000" +def _load_agent_registry_from_env(required: bool = False) -> AgentRegistry | None: + registry_path = os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip() + if not registry_path: + if required: + raise RuntimeError( + "MATRIX_AGENT_REGISTRY_PATH is required when MATRIX_PLATFORM_BACKEND=real" + ) + return None + try: + return load_agent_registry(registry_path) + except (AgentRegistryError, OSError) as exc: + raise RuntimeError(f"failed to load matrix agent registry: {registry_path}") from exc + + def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> PlatformClient: backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower() if backend == "real": prototype_state = PrototypeStateStore() - registry_path = os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip() - if not registry_path: - raise RuntimeError( - "MATRIX_AGENT_REGISTRY_PATH is required when MATRIX_PLATFORM_BACKEND=real" - ) - try: - registry = load_agent_registry(registry_path) - except (AgentRegistryError, OSError) as exc: - raise RuntimeError(f"failed to load matrix agent registry: {registry_path}") from exc + registry = _load_agent_registry_from_env(required=True) + assert registry is not None delegates = { agent.agent_id: RealPlatformClient( agent_id=agent.agent_id, @@ -163,6 +175,7 @@ def build_runtime( settings_mgr = SettingsManager(platform, store) prototype_state = getattr(platform, "_prototype_state", None) agent_base_url = _agent_base_url_from_env() + registry = _load_agent_registry_from_env() dispatcher = EventDispatcher( platform=platform, chat_mgr=chat_mgr, auth_mgr=auth_mgr, settings_mgr=settings_mgr ) @@ -171,6 +184,7 @@ def build_runtime( dispatcher, client=client, store=store, + registry=registry, prototype_state=prototype_state, agent_base_url=agent_base_url, ) @@ -181,6 +195,7 @@ def build_runtime( auth_mgr=auth_mgr, settings_mgr=settings_mgr, dispatcher=dispatcher, + agent_routing_enabled=isinstance(platform, RoutedPlatformClient), ) @@ -244,6 +259,12 @@ class MatrixBot: user=sender, ) return + if not body.startswith("!") and self.runtime.agent_routing_enabled: + block = await self._check_agent_routing(room.room_id, sender, room_meta) + if block is not None: + await self._send_all(room.room_id, block) + return + local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender) incoming = from_room_event(event, room_id=room.room_id, chat_id=local_chat_id) if incoming is None: @@ -574,6 +595,38 @@ class MatrixBot: self.runtime.chat_mgr, ) + async def _check_agent_routing( + self, + room_id: str, + sender: str, + room_meta: dict, + ) -> list[OutgoingEvent] | None: + selected_agent_id = await get_selected_agent_id(self.runtime.store, sender) + if not selected_agent_id: + return [ + OutgoingMessage( + chat_id=room_id, + text="Выбери агент через !agent прежде чем отправлять сообщения.", + ) + ] + room_agent_id = room_meta.get("agent_id") + if room_agent_id and room_agent_id != selected_agent_id: + return [ + OutgoingMessage( + chat_id=room_id, + text=( + f"Этот чат привязан к агенту «{room_agent_id}». " + "Создай новый чат командой !new." + ), + ) + ] + if not room_agent_id: + await set_room_agent_id(self.runtime.store, room_id, selected_agent_id) + await self._ensure_platform_chat_id( + room_id, await get_room_meta(self.runtime.store, room_id) + ) + return None + async def _send_all(self, room_id: str, outgoing: list[OutgoingEvent]) -> None: for event in outgoing: await send_outgoing(self.client, room_id, event, store=self.runtime.store) diff --git a/adapter/matrix/handlers/chat.py b/adapter/matrix/handlers/chat.py index 6ce267c..b5c5dee 100644 --- a/adapter/matrix/handlers/chat.py +++ b/adapter/matrix/handlers/chat.py @@ -8,6 +8,7 @@ from nio.api import RoomVisibility from nio.responses import RoomCreateError from adapter.matrix.store import ( + get_selected_agent_id, get_user_meta, next_chat_id, next_platform_chat_id, @@ -104,18 +105,18 @@ def make_handle_new_chat( state_key=room_id, ) - await set_room_meta( - store, - room_id, - { - "room_type": "chat", - "chat_id": chat_id, - "display_name": room_name, - "matrix_user_id": event.user_id, - "space_id": space_id, - "platform_chat_id": platform_chat_id, - }, - ) + selected_agent_id = await get_selected_agent_id(store, event.user_id) + room_meta: dict = { + "room_type": "chat", + "chat_id": chat_id, + "display_name": room_name, + "matrix_user_id": event.user_id, + "space_id": space_id, + "platform_chat_id": platform_chat_id, + } + if selected_agent_id: + room_meta["agent_id"] = selected_agent_id + await set_room_meta(store, room_id, room_meta) ctx = await chat_mgr.get_or_create( user_id=event.user_id, chat_id=chat_id, diff --git a/tests/adapter/matrix/test_restart_persistence.py b/tests/adapter/matrix/test_restart_persistence.py new file mode 100644 index 0000000..492a94a --- /dev/null +++ b/tests/adapter/matrix/test_restart_persistence.py @@ -0,0 +1,75 @@ +from __future__ import annotations + +import pytest + +from core.store import SQLiteStore +from adapter.matrix.store import ( + PLATFORM_CHAT_SEQ_KEY, + get_room_meta, + get_selected_agent_id, + next_platform_chat_id, + set_room_meta, + set_selected_agent_id, +) + + +async def test_selected_agent_id_survives_restart(tmp_path): + db = str(tmp_path / "state.db") + store = SQLiteStore(db) + await set_selected_agent_id(store, "@alice:example.org", "agent-2") + + store2 = SQLiteStore(db) + assert await get_selected_agent_id(store2, "@alice:example.org") == "agent-2" + + +async def test_room_agent_id_and_platform_chat_id_survive_restart(tmp_path): + db = str(tmp_path / "state.db") + store = SQLiteStore(db) + await set_room_meta(store, "!room:example.org", { + "room_type": "chat", + "agent_id": "agent-1", + "platform_chat_id": "42", + }) + + store2 = SQLiteStore(db) + meta = await get_room_meta(store2, "!room:example.org") + assert meta is not None + assert meta["agent_id"] == "agent-1" + assert meta["platform_chat_id"] == "42" + + +async def test_platform_chat_seq_survives_restart(tmp_path): + db = str(tmp_path / "state.db") + store = SQLiteStore(db) + assert await next_platform_chat_id(store) == "1" + assert await next_platform_chat_id(store) == "2" + assert await next_platform_chat_id(store) == "3" + + store2 = SQLiteStore(db) + assert await next_platform_chat_id(store2) == "4" + + +async def test_routing_state_survives_restart_and_routes_correctly(tmp_path): + db = str(tmp_path / "state.db") + store = SQLiteStore(db) + await set_selected_agent_id(store, "@bob:example.org", "agent-1") + await set_room_meta(store, "!convo:example.org", { + "room_type": "chat", + "agent_id": "agent-1", + "platform_chat_id": "10", + }) + + store2 = SQLiteStore(db) + selected = await get_selected_agent_id(store2, "@bob:example.org") + meta = await get_room_meta(store2, "!convo:example.org") + assert selected == "agent-1" + assert meta is not None + assert meta["agent_id"] == selected + assert meta["platform_chat_id"] == "10" + + +async def test_missing_durable_store_starts_clean(tmp_path): + db = str(tmp_path / "brand_new.db") + store = SQLiteStore(db) + assert await get_selected_agent_id(store, "@nobody:example.org") is None + assert await get_room_meta(store, "!nonexistent:example.org") is None diff --git a/tests/adapter/matrix/test_routing_enforcement.py b/tests/adapter/matrix/test_routing_enforcement.py new file mode 100644 index 0000000..c9a7869 --- /dev/null +++ b/tests/adapter/matrix/test_routing_enforcement.py @@ -0,0 +1,105 @@ +from __future__ import annotations + +import pytest +from unittest.mock import AsyncMock, MagicMock + +from adapter.matrix.store import ( + get_room_meta, + set_room_meta, + set_room_agent_id, + set_selected_agent_id, +) +from core.protocol import IncomingCommand, OutgoingMessage +from core.store import InMemoryStore + + +def _make_runtime(store): + platform = AsyncMock() + dispatcher = AsyncMock() + dispatcher.dispatch.return_value = [OutgoingMessage(chat_id="!r:s", text="ok")] + runtime = MagicMock() + runtime.store = store + runtime.dispatcher = dispatcher + runtime.platform = platform + runtime.agent_routing_enabled = True + return runtime + + +def _make_bot(store): + from adapter.matrix.bot import MatrixBot + client = MagicMock() + client.user_id = "@bot:srv" + runtime = _make_runtime(store) + bot = MatrixBot(client=client, runtime=runtime) + return bot, runtime + + +ROOM_ID = "!room:srv" +USER_ID = "@alice:srv" + + +async def _send_message(bot, body): + from nio import RoomMessageText, MatrixRoom + room = MagicMock(spec=MatrixRoom) + room.room_id = ROOM_ID + event = MagicMock(spec=RoomMessageText) + event.sender = USER_ID + event.body = body + event.source = {} + bot._send_all = AsyncMock() + await bot.on_room_message(room, event) + return bot._send_all + + +async def test_stale_room_blocks_normal_message(): + store = InMemoryStore() + await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, + "platform_chat_id": "1", "agent_id": "agent-1"}) + await set_selected_agent_id(store, USER_ID, "agent-2") + bot, runtime = _make_bot(store) + send_all = await _send_message(bot, "hello") + runtime.dispatcher.dispatch.assert_not_called() + args = send_all.call_args[0] + assert any("agent-1" in m.text and "!new" in m.text for m in args[1]) + + +async def test_stale_room_allows_commands(): + store = InMemoryStore() + await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, + "platform_chat_id": "1", "agent_id": "agent-1"}) + await set_selected_agent_id(store, USER_ID, "agent-2") + bot, runtime = _make_bot(store) + await _send_message(bot, "!help") + runtime.dispatcher.dispatch.assert_called_once() + + +async def test_no_selected_agent_blocks_normal_message(): + store = InMemoryStore() + await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, + "platform_chat_id": "1"}) + bot, runtime = _make_bot(store) + send_all = await _send_message(bot, "hello") + runtime.dispatcher.dispatch.assert_not_called() + args = send_all.call_args[0] + assert any("!agent" in m.text for m in args[1]) + + +async def test_no_selected_agent_allows_commands(): + store = InMemoryStore() + await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, + "platform_chat_id": "1"}) + bot, runtime = _make_bot(store) + await _send_message(bot, "!agent") + runtime.dispatcher.dispatch.assert_called_once() + + +async def test_unbound_room_binds_on_message_when_agent_selected(): + store = InMemoryStore() + await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, + "platform_chat_id": "1"}) + await set_selected_agent_id(store, USER_ID, "agent-1") + bot, runtime = _make_bot(store) + await _send_message(bot, "hello") + meta = await get_room_meta(store, ROOM_ID) + assert meta["agent_id"] == "agent-1" + runtime.dispatcher.dispatch.assert_called_once() From 2a23b30f837f902550137ca653e2c6478ef80f66 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 14:12:07 +0300 Subject: [PATCH 19/55] chore: update STATE after Phase 04 multi-agent follow-up --- .planning/STATE.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/.planning/STATE.md b/.planning/STATE.md index 384ed33..e3451ae 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,8 +2,8 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Ready to execute -last_updated: "2026-04-17T16:10:00.000Z" +status: Phase 04 multi-agent follow-up complete +last_updated: "2026-04-24T14:10:00Z" progress: total_phases: 5 completed_phases: 2 @@ -19,13 +19,21 @@ progress: See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра -**Current focus:** Phase 04 complete — Matrix MVP implementation ready for testing +**Current focus:** Phase 04 multi-agent routing follow-up fully implemented; ready for live validation or Phase 05 planning ## Current Phase -**Phase 4** implementation complete: Matrix MVP +**Phase 4** implementation complete: Matrix MVP + multi-agent routing -Phase 4 is implemented. Next step is manual and automated testing of the Matrix MVP flow before deciding on follow-up work. +All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-direct-agent-prototype`: + +- `7627012` / `242f4aa` / `9ccba16` — agent registry loader, RoutedPlatformClient facade, fail-fast on missing registry in real mode +- `a65227e` — dispatch chat_id contract alignment +- `74cf028` — `!agent` command, `selected_agent_id` persistence, unbound-room binding on first selection +- `7623039` — attachment normalization in core message handler +- `e733119` — stale room blocking, `agent_id` binding on `!new`, durable restart state tests + +135 Matrix tests pass. The branch is ready for review and merge. ## Decisions @@ -46,6 +54,12 @@ Phase 4 is implemented. Next step is manual and automated testing of the Matrix - [Phase 04]: Replaced AgentSessionClient with AgentApiWrapper and persistent agent connection lifecycle in Matrix runtime. - [Phase 04]: Added !save, !load, !reset, and !context commands with pending-state interception and local prototype session metadata. - [Phase 04]: Added Matrix-only Docker packaging for MVP deployment; platform services remain external to this compose setup. +- [Phase 04]: Replaced the Matrix prod path again with direct upstream `AgentApi` per request; removed the local runtime wrapper from the prod flow. +- [Phase 04]: Adopted `AGENT_BASE_URL` as the primary runtime contract and kept `AGENT_WS_URL` only as backward-compatible env fallback. +- [Phase 04 follow-up]: Kept shared PlatformClient unchanged; introduced Matrix-specific RoutedPlatformClient to avoid breaking Telegram adapter. +- [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient). +- [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata. +- [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test. ## Blockers @@ -57,6 +71,7 @@ Phase 4 is implemented. Next step is manual and automated testing of the Matrix - Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT) - Phase 4 added: Matrix MVP: shared agent context and context management command +- Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence) - New platform signal: upcoming proper `chat_id` support should enable file-level context separation and stronger context management in a future follow-up phase. ## Performance Metrics @@ -68,12 +83,14 @@ Phase 4 is implemented. Next step is manual and automated testing of the Matrix | 01 | 03 | 3 min | 2 | 5 | 2026-04-02T19:57:34Z | | 01 | 04 | 3 min | 2 | 7 | 2026-04-02T20:03:38Z | | 01 | 05 | 2 min | 2 | 7 | 2026-04-03T09:28:47Z | -| 01 | 06 | 4 min | 2 | 7 | 2026-04-03T09:35:39Z | +| 01 | 06 | 4 min | 2 | 7 | 2026-04-03T09:35:47Z | | 04 | 01 | 1 session | 1 wave | 8 | 2026-04-17 | | 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 | | 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | +| 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | ## Session -- Last session: 2026-04-17T16:10:00Z -- Stopped at: Phase 4 implementation complete, ready for testing +- Last session: 2026-04-24T14:10:00Z +- Stopped at: Phase 04 multi-agent follow-up fully committed (e733119); 135 tests green; branch feat/matrix-direct-agent-prototype ready for review/merge +- Resume file: HANDOFF deleted; no pending tasks From c34db0e6c01c3729593b83ba6528ae0e5a88b024 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Fri, 24 Apr 2026 15:17:08 +0300 Subject: [PATCH 20/55] =?UTF-8?q?wip:=20first-chunk=20debug=20logging=20?= =?UTF-8?q?=E2=80=94=20paused=20waiting=20for=20platform-agent=20logs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/HANDOFF.json | 98 +++++-------------- .../.continue-here.md | 59 +++++------ config/matrix-agents.example.yaml | 4 +- docker-compose.yml | 1 + sdk/real.py | 10 ++ 5 files changed, 61 insertions(+), 111 deletions(-) diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json index a0e2123..65c6bdb 100644 --- a/.planning/HANDOFF.json +++ b/.planning/HANDOFF.json @@ -1,90 +1,38 @@ { "version": "1.0", - "timestamp": "2026-04-23T11:46:45.938Z", + "timestamp": "2026-04-24T12:16:09.301Z", "phase": "04", - "phase_name": "Matrix MVP: shared agent context and context management commands", - "phase_dir": ".planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma", - "plan": 3, - "task": 3, - "total_tasks": 3, + "phase_name": "matrix-mvp-shared-agent-context-and-context-management", + "phase_dir": "04-matrix-mvp-shared-agent-context-and-context-management-comma", + "plan": null, + "task": null, + "total_tasks": null, "status": "paused", "completed_tasks": [ - { - "id": 1, - "name": "Стабилизировать Matrix MVP runtime: numeric platform_chat_id mapping, staged attachments, clean vendored platform repos", - "status": "done", - "commit": "4524a6a" - }, - { - "id": 2, - "name": "Локализовать missing-first-chunk bug, оформить финальный bug report и очистить runtime до thin upstream integration boundary", - "status": "done", - "commit": "0c2884c" - }, - { - "id": 3, - "name": "Перейти на direct upstream AgentApi per request, убрать local wrapper из prod path и зафиксировать AGENT_BASE_URL как основной runtime contract", - "status": "done", - "commit": "7d58dd1" - } + {"id": 1, "name": "docker-compose config mount + MATRIX_AGENT_REGISTRY_PATH", "status": "done"}, + {"id": 2, "name": "debug logging in sdk/real.py (_stream_agent_events)", "status": "done"}, + {"id": 3, "name": "debug logging in platform-agent service.py", "status": "done"} ], "remaining_tasks": [ - { - "id": 4, - "name": "Решить, закрываем ли Phase 04 окончательно или продолжаем Matrix через live smoke в реальном окружении", - "status": "not_started" - }, - { - "id": 5, - "name": "Если двигаемся дальше по Matrix, прогнать text/tool/file smoke на direct AgentApi per-request path и проверить отсутствие regressions", - "status": "not_started" - }, - { - "id": 6, - "name": "Если начинаем новую surface, открыть follow-up phase для prod messenger architecture без собственного transport layer", - "status": "not_started" - } - ], - "blockers": [ - { - "description": "В worktree остаётся посторонний локальный diff в core/handlers/message.py, не связанный с direct AgentApi fix", - "type": "technical", - "workaround": "Не смешивать с runtime/surface работой без отдельной задачи; handoff commit этот файл не включает" - } + {"id": 4, "name": "run docker compose up --build and get platform-agent logs with stream_event lines", "status": "not_started"}, + {"id": 5, "name": "analyze logs: content_type and langgraph_node to find where first chunk is lost", "status": "not_started"}, + {"id": 6, "name": "fix in service.py based on findings (filter by node, handle list content, or capture subagent output)", "status": "not_started"} ], + "blockers": [], "human_actions_pending": [ - { - "action": "Выбрать следующий трек: Matrix live validation или планирование новой prod surface вроде Telegram/Max", - "context": "Кодовый фикс уже сделан и запушен; дальше работа зависит от продуктового направления, а не от transport-debug", - "blocking": false - }, - { - "action": "При следующем отдельном planning/cleanup коммите привести STATE/roadmap в полное соответствие с direct upstream per-request решением", - "context": "Локальный STATE уже обновлён как checkpoint, но handoff WIP commit включает только HANDOFF и .continue-here", - "blocking": false - } + {"action": "run docker compose up --build and reproduce the alphabet/image truncation bug", "context": "Need platform-agent logs with DEBUG level to see stream_event lines", "blocking": true} ], "decisions": [ - { - "decision": "Для prod path Matrix surface больше не держит собственный transport layer; используется прямой upstream AgentApi с fresh connection per request", - "rationale": "Это убрало reuse-sensitive загрязнение между запросами, после чего missing-first-chunk симптом перестал воспроизводиться локально", - "phase": "04" - }, - { - "decision": "AGENT_BASE_URL принят как основной runtime contract; AGENT_WS_URL оставлен только как backward-compat fallback в env wiring", - "rationale": "Так surface говорит с платформой по их реальному API contract, а не через локальный ws shim", - "phase": "04" - }, - { - "decision": "Для следующих surfaces не строить custom transport wrapper поверх платформы", - "rationale": "Surface должна владеть integration/session boundary, а не альтернативной stream semantics", - "phase": "04" - } + {"decision": "Bug is in platform-agent service.py __astream, not in surfaces bot", "rationale": "Logs show first text chunk already truncated at index=0 level", "phase": "04"}, + {"decision": "deepagents uses dispatcher+subagent architecture", "rationale": "create_deep_agent wraps SubAgentMiddleware with general-purpose subagent", "phase": "04"}, + {"decision": "astream_events v2 processes on_chat_model_stream from ALL nodes without filtering", "rationale": "service.py has no namespace/node filtering", "phase": "04"} ], "uncommitted_files": [ - ".planning/STATE.md", - "core/handlers/message.py" + "sdk/real.py (debug logging added)", + "docker-compose.yml (config volume mount added)", + "config/matrix-agents.example.yaml (label names updated)", + "external/platform-agent/src/agent/service.py (debug logging added, in submodule)" ], - "next_action": "При возобновлении сначала прочитать обновлённый handoff, затем выбрать один из двух треков: либо Matrix live smoke на direct AgentApi per-request path, либо новая phase/spec для prod surface без собственного transport layer", - "context_notes": "Старый checkpoint про platform triage устарел. После диалога с платформой runtime переведён на прямой upstream AgentApi с fresh connection per request, локальный wrapper убран из prod path, tests прошли, commit 7d58dd1 запушен в origin/feat/matrix-direct-agent-prototype. Важный вывод для будущей архитектуры surfaces: upstream transport считать authoritative, а локально держать только lifecycle, serialization, attachment forwarding, error mapping и reconciliation." + "next_action": "Run: docker compose up --build. Send a message that triggers the bug (e.g. 'Напомни алфавит' after sending an image). Look for stream_event lines in platform-agent-1 logs. Check content_type and langgraph_node values for truncated responses.", + "context_notes": "Investigating first-chunk truncation bug in Matrix bot responses. The bug appears when agent uses tools (image analysis) OR when images are in context. Platform-agent uses deepagents framework (dispatcher+subagent pattern). The hypothesis is that on_chat_model_stream events from multiple graph nodes are all forwarded as MsgEventTextChunk without filtering, OR that chunk.content is sometimes a list instead of str causing validation issues. Added logging to confirm. The fix will likely be in service.py: either filter by langgraph_node or handle list content type." } diff --git a/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md b/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md index a009302..c1b108a 100644 --- a/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md +++ b/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md @@ -1,62 +1,53 @@ --- +context: phase phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma -task: 3 -total_tasks: 3 -status: paused -last_updated: 2026-04-23T11:46:45.938Z +task: 4 +total_tasks: 6 +status: in_progress +last_updated: 2026-04-24T12:16:09.301Z --- -Phase 04 кодово стабилизирована вокруг direct upstream `AgentApi` per request. Коммит `7d58dd1` уже запушен в `origin/feat/matrix-direct-agent-prototype`. Старый checkpoint в этом файле устарел: после обратной связи от платформы мы убрали extra wrapper из prod path, перестали переиспользовать один websocket между запросами и после этого missing-first-chunk симптом перестал воспроизводиться локально. +Debugging first-chunk truncation bug in Matrix bot. Logging added to both sdk/real.py and external/platform-agent/src/agent/service.py. Waiting for user to run docker compose up --build and share platform-agent logs with stream_event lines. -- Весь ранее собранный Matrix MVP контекст остаётся валидным: numeric `platform_chat_id`, staged attachments, shared workspace, context commands и Docker packaging уже на месте. -- Продовый runtime path переведён на direct upstream client через `sdk/upstream_agent_api.py`; локальный `sdk/agent_api_wrapper.py` удалён из runtime path. -- `sdk/real.py` теперь на каждый `send_message` и `stream_message` создаёт новый `AgentApi`, делает `connect()`, читает stream и сразу `close()`. -- `AGENT_BASE_URL` зафиксирован как основной runtime contract; `AGENT_WS_URL` оставлен только как backward-compat fallback в env wiring. -- Добавлена регрессия на reuse-sensitive missing-first-chunk сценарий и обновлены runtime/integration tests; `uv run pytest tests -q` прошёл (`196 passed`), `ruff` на затронутых файлах clean. -- Кодовый фикс закоммичен и запушен: `7d58dd1` (`fix: use direct agent api per request`). -- В сессионных выводах зафиксирован новый архитектурный принцип для следующих surfaces: не строить свой transport layer, держать только thin integration/session boundary над upstream transport. +- docker-compose.yml: added `./config:/app/config:ro` volume mount so MATRIX_AGENT_REGISTRY_PATH works +- config/matrix-agents.example.yaml: updated labels to Platform/Media +- sdk/real.py: added structlog debug logging in _stream_agent_events (logs each chunk index + text[:40]) +- external/platform-agent/src/agent/service.py: added logging of langgraph_node, content_type, content[:60] for every on_chat_model_stream event + +Bot is running and user confirmed it starts correctly with MATRIX_PLATFORM_BACKEND=real. -- Перед следующим кодом выбрать направление: - - если продолжаем Matrix, прогнать live smoke в реальном окружении на text/tool/file flow и проверить отсутствие regressions на direct per-request path; - - если переходим к Telegram/Max-подобной работе, открыть новую phase/spec под prod surface architecture. -- Привести `.planning/STATE.md` и roadmap в полностью каноничное состояние отдельным planning/cleanup шагом, если хотим закрепить этот checkpoint не только через handoff. -- Не смешивать дальнейшую surface/runtime работу с отдельным локальным diff в `core/handlers/message.py`, пока это не станет явной задачей. +- Task 4: Get platform-agent debug logs (docker compose up --build, reproduce truncation, share stream_event lines) +- Task 5: Analyze: check content_type (str vs list), check langgraph_node (which graph node produces the first chunk) +- Task 6: Fix service.py based on findings -- Matrix prod path должен использовать прямой upstream `AgentApi`, а не surface-owned wrapper с кастомной stream semantics. -- Fresh connection per request принят как дефолтный lifecycle для этой surface, потому что именно reuse websocket оказался чувствительной точкой для missing-first-chunk симптома. -- `AGENT_BASE_URL` это честный runtime contract; ws URL normalization допустим только как backward-compat env fallback. -- Для следующих surfaces надо думать терминами `integration boundary` и `runtime contract`, а не терминами "написать свой transport layer". +- Bug confirmed to be in platform-agent, NOT in surfaces bot: our sdk/real.py logs show chunk index=0 already has truncated text (e.g. ' Д Е Ё...' instead of 'А Б В Г Д...') +- deepagents framework uses SubAgentMiddleware: main dispatcher agent + general-purpose subagent +- service.py processes ALL on_chat_model_stream events from astream_events v2 with no node filtering +- Two leading hypotheses: (A) chunk.content is a list for some events (multimodal), causing silent skip/error; (B) events from wrong graph node are being captured/not captured -- Подтверждённого локального Matrix blocker после `7d58dd1` больше нет; дальше это вопрос product direction и live validation, а не active transport-firefight. -- В worktree остаётся посторонний локальный diff в `core/handlers/message.py`; не смешивать его с будущими surface/runtime изменениями без отдельной задачи. +- Need user to run docker compose up --build and share platform-agent logs with DEBUG output -Важная ментальная модель теперь такая: +The deepagents architecture: create_deep_agent creates a main orchestrator with SubAgentMiddleware wrapping a general-purpose subagent. When astream_events v2 runs, it may emit on_chat_model_stream from both the main agent's LLM call AND the subagent's LLM call. service.py captures ALL of them. The first chunk of the actual response might be from the subagent (not forwarded to client properly), while the main agent's response starts mid-sentence because it "sees" the subagent's output in its tool result context. -- upstream transport authoritative; `surfaces` владеет только lifecycle, serialization, attachment forwarding, error mapping и reconciliation. -- Старый narrative "ждём platform triage перед любыми transport changes" больше не актуален; transport change уже сделан и дал положительный эффект. -- Предыдущий handoff и текущий `STATE.md` были написаны до этого решения, поэтому их надо читать как исторический контекст, а не как последнюю истину. -- Проверка на false completion ничего критичного не показала: grep задел только фразу "compatibility placeholder" в `04-01-SUMMARY.md`, а не реальный незаполненный summary. -- Текущие локальные non-handoff diff: `.planning/STATE.md` и `core/handlers/message.py`. +Two key things to look for in logs: +1. content_type=list → fix is `chunk.content[0].get("text", "")` or similar +2. langgraph_node varies between chunks → fix is to filter to the correct node (e.g. only "agent" node) -Start with: - -1. Открыть этот обновлённый handoff, а не опираться на старый checkpoint про platform triage. -2. Выбрать трек: Matrix live smoke или новая prod-surface phase. -3. Если снова полезем в runtime, не возвращать custom transport wrapper и persistent shared websocket без очень сильной причины и регрессионных тестов. +Start with: docker compose up --build. Then send a message with image context (e.g. send an image first, then ask 'Напомни алфавит'). Share platform-agent-1 logs — specifically the stream_event lines showing ns= and content_type= values. diff --git a/config/matrix-agents.example.yaml b/config/matrix-agents.example.yaml index 23d4b37..96ddce9 100644 --- a/config/matrix-agents.example.yaml +++ b/config/matrix-agents.example.yaml @@ -1,5 +1,5 @@ agents: - id: agent-1 - label: Analyst + label: Platform - id: agent-2 - label: Research + label: Media diff --git a/docker-compose.yml b/docker-compose.yml index 4de9fac..c7323d0 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -32,6 +32,7 @@ services: - platform-agent volumes: - workspace:/workspace + - ./config:/app/config:ro restart: unless-stopped volumes: diff --git a/sdk/real.py b/sdk/real.py index 0b7ef19..792c6c1 100644 --- a/sdk/real.py +++ b/sdk/real.py @@ -4,6 +4,8 @@ import asyncio from collections.abc import AsyncIterator from pathlib import Path +import structlog + from sdk.interface import ( Attachment, MessageChunk, @@ -16,6 +18,8 @@ from sdk.interface import ( from sdk.prototype_state import PrototypeStateStore from sdk.upstream_agent_api import AgentApi, MsgEventSendFile, MsgEventTextChunk +logger = structlog.get_logger(__name__) + class RealPlatformClient(PlatformClient): def __init__( @@ -157,7 +161,13 @@ class RealPlatformClient(PlatformClient): ) -> AsyncIterator[object]: attachment_paths = self._attachment_paths(attachments) event_stream = chat_api.send_message(text, attachments=attachment_paths or None) + chunk_index = 0 async for event in event_stream: + if isinstance(event, MsgEventTextChunk): + logger.debug("agent_chunk", index=chunk_index, text=repr(event.text[:40])) + chunk_index += 1 + else: + logger.debug("agent_event", index=chunk_index, type=type(event).__name__) yield event def _build_chat_api(self, chat_id: str): From 8ffbe7b6b3ef2ca270da1fb41c1704bd06d46533 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 21:46:27 +0300 Subject: [PATCH 21/55] =?UTF-8?q?wip:=20deployment=20architecture=20resear?= =?UTF-8?q?ch=20=E2=80=94=20Phase=2005=20ready=20to=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/deploy-architecture.md: full deployment topology, agent API, file transfer via shared volume - .planning/HANDOFF.json + .continue-here.md: session state for Phase 05 planning --- .planning/.continue-here.md | 72 ++++++++++++++++++ .planning/HANDOFF.json | 112 +++++++++++++++++++++------- .planning/STATE.md | 8 +- docs/deploy-architecture.md | 145 ++++++++++++++++++++++++++++++++++++ 4 files changed, 308 insertions(+), 29 deletions(-) create mode 100644 .planning/.continue-here.md create mode 100644 docs/deploy-architecture.md diff --git a/.planning/.continue-here.md b/.planning/.continue-here.md new file mode 100644 index 0000000..f27ae84 --- /dev/null +++ b/.planning/.continue-here.md @@ -0,0 +1,72 @@ +--- +context: pre-planning +phase: 05-deployment +task: 0 +total_tasks: 0 +status: ready-to-plan +last_updated: 2026-04-27T18:44:51.832Z +--- + + +Phase 04 полностью завершена и закоммичена на ветке `feat/matrix-direct-agent-prototype` (135 тестов зелёные). Этот сеанс был посвящён архитектуре деплоя — изучили платформенные репозитории и обсудили топологию с командой платформы. Вся информация о деплое зафиксирована в `docs/deploy-architecture.md`. Phase 05 не спланирована, следующий шаг — `/gsd-plan-phase`. + + + + +- Изучены актуальные версии platform-agent, platform-agent_api, platform-master +- Уточнена топология деплоя с платформой (схема с reverse proxy и shared volume) +- Созданы `docs/deploy-architecture.md` — полное summary архитектуры деплоя + + + + +- Смержить `feat/matrix-direct-agent-prototype` → `main` +- Спланировать Phase 05 (деплой) +- Выполнить Phase 05: + - Обновить `config/matrix-agents.yaml` (добавить `base_url`, `workspace_path`, `user_agents`) + - Обновить `sdk/real.py` (AgentApi конструктор, file transfer) + - Обработка `MsgEventSendFile` в Matrix адаптере (скачать файл из volume, отправить пользователю) + - Обработка входящих файлов от Matrix пользователей (сохранить в workspace, передать в attachments) + - Написать `docker-compose.yml` для деплоя + + + + +- **Топология**: один инстанс Matrix-бота, один агент-контейнер на пользователя, reverse proxy на `lambda.coredump.ru:7000` роутит по пути `/agent_N/` +- **Файлы**: через shared volume `/agents/`. Surface пишет файл в `/agents/{N}/`, передаёт относительный путь в `attachments=["file.txt"]`. При `MsgEventSendFile(path)` — читает файл из `/agents/{N}/{path}` и шлёт в Matrix. +- **Agent API**: используем master (`attachments` и `MsgEventSendFile` есть). Ветку `#9-clientside-tool-call` игнорируем — она в разработке и убирает нужные фичи. +- **Конфиг**: два словаря — `user_id → agent_id` и `agent_id → {base_url, workspace_path}` +- **Master**: не используем для MVP. Статический конфиг. При готовности Master — мигрируем. +- **chat_id**: пока `chat_id=0` (один контекст на пользователя) + + + + +- **AGENT_ID + COMPOSIO_API_KEY**: Composio смержен в main platform-agent, теперь обязателен. Значения нужны от Азамата перед деплоем. +- **agent_api #9**: убирает `attachments` и `MsgEventSendFile` — если смержат до деплоя, сломает наш file transfer. Нужно уточнить сроки. + + +## Required Reading (in order) + +1. `docs/deploy-architecture.md` — полная архитектура деплоя, топология, API, файловый обмен, конфиг +2. `adapter/matrix/routed_platform.py` — текущий RoutedPlatformClient +3. `sdk/real.py` — текущий AgentApi wrapper +4. `config/matrix-agents.yaml` и `config/matrix-agents.example.yaml` — текущий формат конфига (нужно расширить) + +## Infrastructure State + +- Ветка: `feat/matrix-direct-agent-prototype` — готова к merge, 135 тестов зелёные +- `config/matrix-agents.yaml` — незакоммичен (live config, добавить в `.gitignore`) +- `docs/deploy-architecture.md` — незакоммичен (новый файл этого сеанса) +- platform-agent main: Composio уже смержен (требует `AGENT_ID`, `COMPOSIO_API_KEY` в env) + + +Архитектура деплоя полностью прояснена. Нет неизвестных блокеров (кроме env-переменных от платформы). Phase 05 — чисто инженерная задача: обновить конфиг, sdk, Matrix адаптер, написать compose. Всё что нужно знать — в docs/deploy-architecture.md. + + + +1. /clear +2. /gsd-resume-work — прочитает этот файл и предложит план Phase 05 +3. Прочитать docs/deploy-architecture.md +4. /gsd-plan-phase 05 + diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json index 65c6bdb..853265c 100644 --- a/.planning/HANDOFF.json +++ b/.planning/HANDOFF.json @@ -1,38 +1,100 @@ { "version": "1.0", - "timestamp": "2026-04-24T12:16:09.301Z", - "phase": "04", - "phase_name": "matrix-mvp-shared-agent-context-and-context-management", - "phase_dir": "04-matrix-mvp-shared-agent-context-and-context-management-comma", - "plan": null, - "task": null, - "total_tasks": null, - "status": "paused", + "timestamp": "2026-04-27T18:44:51.832Z", + "phase": "05", + "phase_name": "deployment", + "phase_dir": null, + "plan": 0, + "task": 0, + "total_tasks": 0, + "status": "pre-planning", "completed_tasks": [ - {"id": 1, "name": "docker-compose config mount + MATRIX_AGENT_REGISTRY_PATH", "status": "done"}, - {"id": 2, "name": "debug logging in sdk/real.py (_stream_agent_events)", "status": "done"}, - {"id": 3, "name": "debug logging in platform-agent service.py", "status": "done"} + { + "id": 1, + "name": "Research platform repos (agent, agent_api, master)", + "status": "done", + "commit": null + }, + { + "id": 2, + "name": "Clarify deployment topology with platform team", + "status": "done", + "commit": null + }, + { + "id": 3, + "name": "Create docs/deploy-architecture.md", + "status": "done", + "commit": null + } ], "remaining_tasks": [ - {"id": 4, "name": "run docker compose up --build and get platform-agent logs with stream_event lines", "status": "not_started"}, - {"id": 5, "name": "analyze logs: content_type and langgraph_node to find where first chunk is lost", "status": "not_started"}, - {"id": 6, "name": "fix in service.py based on findings (filter by node, handle list content, or capture subagent output)", "status": "not_started"} + {"id": 4, "name": "Merge feat/matrix-direct-agent-prototype → main", "status": "not_started"}, + {"id": 5, "name": "Plan Phase 05 (deployment)", "status": "not_started"}, + {"id": 6, "name": "Execute Phase 05", "status": "not_started"} + ], + "blockers": [ + { + "description": "agent_api #9-clientside-tool-call убирает attachments и MsgEventSendFile — если смержат до деплоя, сломает file transfer", + "type": "external", + "workaround": "Используем master пока #9 не merged. Уточнить у Азамата сроки." + }, + { + "description": "AGENT_ID и COMPOSIO_API_KEY значения для каждого агента — нужны от платформы", + "type": "human_action", + "workaround": "Запросить у Азамата перед деплоем" + } ], - "blockers": [], "human_actions_pending": [ - {"action": "run docker compose up --build and reproduce the alphabet/image truncation bug", "context": "Need platform-agent logs with DEBUG level to see stream_event lines", "blocking": true} + { + "action": "Получить значения AGENT_ID и COMPOSIO_API_KEY для каждого агента от платформы", + "context": "Composio смержен в main platform-agent, теперь обязателен", + "blocking": true + }, + { + "action": "Уточнить у Азамата сроки мержа agent_api #9 (убирает attachments/MsgEventSendFile)", + "context": "Мы строим file transfer на этих фичах из master", + "blocking": false + }, + { + "action": "Уточнить: chat_id=0 для всех или используем разные chat_id для C1/C2/C3", + "context": "Платформа показала пример с одним AgentApi на агента без явного chat_id", + "blocking": false + } ], "decisions": [ - {"decision": "Bug is in platform-agent service.py __astream, not in surfaces bot", "rationale": "Logs show first text chunk already truncated at index=0 level", "phase": "04"}, - {"decision": "deepagents uses dispatcher+subagent architecture", "rationale": "create_deep_agent wraps SubAgentMiddleware with general-purpose subagent", "phase": "04"}, - {"decision": "astream_events v2 processes on_chat_model_stream from ALL nodes without filtering", "rationale": "service.py has no namespace/node filtering", "phase": "04"} + { + "decision": "Один инстанс Matrix-бота на всех пользователей, один агент-контейнер на пользователя", + "rationale": "Подтверждено платформой. Reverse proxy на lambda.coredump.ru:7000 роутит по пути /agent_N/", + "phase": "pre-05" + }, + { + "decision": "Файлы через shared volume /agents/, не через API", + "rationale": "Surface и агент видят один volume. Surface пишет файл → передаёт путь в attachments. Агент эмитит MsgEventSendFile → Surface читает файл и шлёт в Matrix", + "phase": "pre-05" + }, + { + "decision": "Используем agent_api master (с attachments и MsgEventSendFile), не ветку #9", + "rationale": "master стабильный, #9 в разработке и убирает нужные нам фичи", + "phase": "pre-05" + }, + { + "decision": "Конфиг: два словаря — user_id→agent_id и agent_id→{base_url, workspace_path}", + "rationale": "Платформа подтвердила статический маппинг для MVP без Master", + "phase": "pre-05" + }, + { + "decision": "Master (platform-master feat/storage) не используем для MVP", + "rationale": "Ещё в разработке. Используем статический конфиг. При готовности Master — мигрируем.", + "phase": "pre-05" + } ], "uncommitted_files": [ - "sdk/real.py (debug logging added)", - "docker-compose.yml (config volume mount added)", - "config/matrix-agents.example.yaml (label names updated)", - "external/platform-agent/src/agent/service.py (debug logging added, in submodule)" + "docs/deploy-architecture.md", + "docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md", + "config/matrix-agents.yaml", + ".planning/STATE.md" ], - "next_action": "Run: docker compose up --build. Send a message that triggers the bug (e.g. 'Напомни алфавит' after sending an image). Look for stream_event lines in platform-agent-1 logs. Check content_type and langgraph_node values for truncated responses.", - "context_notes": "Investigating first-chunk truncation bug in Matrix bot responses. The bug appears when agent uses tools (image analysis) OR when images are in context. Platform-agent uses deepagents framework (dispatcher+subagent pattern). The hypothesis is that on_chat_model_stream events from multiple graph nodes are all forwarded as MsgEventTextChunk without filtering, OR that chunk.content is sometimes a list instead of str causing validation issues. Added logging to confirm. The fix will likely be in service.py: either filter by langgraph_node or handle list content type." + "next_action": "Запустить /gsd-plan-phase 05 для планирования фазы деплоя. Прочитать docs/deploy-architecture.md перед планированием.", + "context_notes": "Phase 04 полностью завершена, ветка feat/matrix-direct-agent-prototype готова к merge. Этот сеанс был посвящён архитектуре деплоя — исследовали платформу, обсуждали с командой. Всё что знаем про деплой — в docs/deploy-architecture.md. Phase 05 = деплой: обновить конфиг, sdk/real.py, добавить file transfer в Matrix адаптер, написать docker-compose." } diff --git a/.planning/STATE.md b/.planning/STATE.md index e3451ae..5d87f69 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,8 +2,8 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Phase 04 multi-agent follow-up complete -last_updated: "2026-04-24T14:10:00Z" +status: Phase 04 complete — deployment architecture clarified, Phase 05 ready to plan +last_updated: "2026-04-27T18:44:51Z" progress: total_phases: 5 completed_phases: 2 @@ -92,5 +92,5 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d ## Session - Last session: 2026-04-24T14:10:00Z -- Stopped at: Phase 04 multi-agent follow-up fully committed (e733119); 135 tests green; branch feat/matrix-direct-agent-prototype ready for review/merge -- Resume file: HANDOFF deleted; no pending tasks +- Stopped at: Deployment architecture clarified with platform team; docs/deploy-architecture.md written; Phase 05 ready to plan +- Resume file: .planning/.continue-here.md diff --git a/docs/deploy-architecture.md b/docs/deploy-architecture.md new file mode 100644 index 0000000..8746e56 --- /dev/null +++ b/docs/deploy-architecture.md @@ -0,0 +1,145 @@ +# Deployment Architecture — Matrix Bot + Agents + +> Сформировано 2026-04-27 по итогам обсуждения с платформой. + +--- + +## Топология + +``` +lambda.coredump.ru +├── :7000 (reverse proxy, path-based routing) +│ ├── /agent_0/ → agent_0 container +│ ├── /agent_1/ → agent_1 container +│ └── /agent_N/ → agent_N container +│ +└── Matrix bot instance (один инстанс на всех) + └── volume /agents/ (shared с агентами) + ├── /agents/0/ ← workspace agent_0 + ├── /agents/1/ ← workspace agent_1 + └── /agents/N/ +``` + +- **Один инстанс Matrix-бота** обслуживает всех пользователей. +- **Один агент-контейнер на пользователя.** Изоляция по agent_id, не через chat_id внутри одного инстанса. +- **Shared volume** `/agents/` смонтирован и в Matrix-бот, и в каждый агент-контейнер. Агент видит свой подкаталог как `/workspace`. + +--- + +## Конфиг (два словаря) + +```yaml +# config/matrix-agents.yaml + +user_agents: + "@user0:matrix.lambda.coredump.ru": agent-0 + "@user1:matrix.lambda.coredump.ru": agent-1 + "@user2:matrix.lambda.coredump.ru": agent-2 + +agents: + - id: agent-0 + label: "Agent 0" + base_url: "ws://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0/" + + - id: agent-1 + label: "Agent 1" + base_url: "ws://lambda.coredump.ru:7000/agent_1/" + workspace_path: "/agents/1/" +``` + +- `user_agents` — маппинг Matrix user_id → agent_id (статический, выдаётся платформой) +- `agents` — маппинг agent_id → URL агента и путь к его workspace на shared volume + +--- + +## Agent API (используем master ветку `platform/agent_api`) + +```python +from lambda_agent_api.agent_api import AgentApi + +connected_agents: dict[str, AgentApi] = {} + +def on_agent_disconnect(agent: AgentApi): + del connected_agents[agent.id] + +async def on_message(matrix_user_id: str, text: str): + agent_id = get_agent_id_by_user(matrix_user_id) # из user_agents конфига + + agent = connected_agents.get(agent_id) + if not agent: + agent = AgentApi( + agent_id, + get_agent_base_url(agent_id), # ws://lambda.coredump.ru:7000/agent_0/ + on_disconnect=on_agent_disconnect, + chat_id=0, # default, один чат на агента + ) + await agent.connect() + connected_agents[agent_id] = agent + + async for event in agent.send_message(text): + ... +``` + +**Параметры конструктора (master):** +```python +AgentApi( + agent_id: str, + base_url: str, # ws://host:port/agent_N/ + chat_id: int = 0, # default — один чат на агента + on_disconnect: callable, +) +``` + +**Lifecycle:** агент автоматически отключается после нескольких минут бездействия. +`on_disconnect` удаляет из пула → следующее сообщение создаёт новое соединение. + +--- + +## Передача файлов + +### Пользователь → Агент (входящий файл) + +1. Matrix-бот получает файл от пользователя +2. Сохраняет в workspace агента: `/agents/{N}/incoming/{filename}` +3. Вызывает `agent.send_message(text, attachments=["incoming/filename"])` + — путь относительно `/workspace` агента + +### Агент → Пользователь (исходящий файл) + +1. Агент эмитит `MsgEventSendFile(path="output/report.pdf")` +2. Matrix-бот читает файл: `/agents/{N}/output/report.pdf` +3. Отправляет как Matrix file message пользователю + +**Ключевое:** поверхность видит `/agents/` целиком через shared volume. Прямой HTTP-доступ к файлам не нужен. + +--- + +## Текущее состояние platform-agent (main) + +- Composio интегрирован в main (`#9-интеграция-composIO`) +- Агент требует в `.env`: `AGENT_ID`, `COMPOSIO_API_KEY` +- Backend: `IsolatedShellBackend` (main) / `CompositeBackend` (ветка `#19`, не merged) +- Memory: `MemorySaver` — история слетает при рестарте контейнера (known limitation) + +--- + +## platform-master (будущее, пока не используем) + +Ветка `feat/storage` реализует реальный Master-сервис: +- `POST /api/v1/create {chat_id}` → поднимает/переиспользует sandbox-контейнер +- TTL-based lifecycle (300с default, конфигурируемо) +- `ChatStorage` — API для upload/download файлов через Master +- Auth + p2p lease — вне текущего scope MVP + +**Для деплоя MVP используем статический конфиг без Master.** +При готовности Master: `get_agent_url()` будет вызывать `POST /api/v1/create`, URL возвращается в ответе. + +--- + +## Что НЕ решено / открытые вопросы + +- Ветка `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока игнорируем, используем master. Уточнить у Азамата сроки мержа перед деплоем. +- `chat_id` — при нашей модели C1/C2/C3 каждый чат должен иметь отдельный `chat_id`. Нужно решить: один `AgentApi` на агента (chat_id=0) или по инстансу на чат (chat_id=1/2/3). Пока берём `chat_id=0` (один контекст на пользователя). +- Composio `AGENT_ID` в `.env` для каждого агента — уточнить у платформы значения. +- Что происходит с историей при рестарте агента — `MemorySaver` не персистентный. From 655332000156a84b54b5294f89d6b1097f211a86 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 22:13:52 +0300 Subject: [PATCH 22/55] docs(05): capture phase context --- .../phases/05-mvp-deployment/05-CONTEXT.md | 130 ++++++++++++++++++ .../05-mvp-deployment/05-DISCUSSION-LOG.md | 65 +++++++++ 2 files changed, 195 insertions(+) create mode 100644 .planning/phases/05-mvp-deployment/05-CONTEXT.md create mode 100644 .planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md diff --git a/.planning/phases/05-mvp-deployment/05-CONTEXT.md b/.planning/phases/05-mvp-deployment/05-CONTEXT.md new file mode 100644 index 0000000..b0d2e81 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-CONTEXT.md @@ -0,0 +1,130 @@ +# Phase 05: MVP Deployment — Context + +**Gathered:** 2026-04-27 +**Status:** Ready for planning + + +## Phase Boundary + +Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru: +1. Расширить config/matrix-agents.yaml — добавить user_agents (Matrix user_id → agent_id) и per-agent base_url/workspace_path +2. Обновить AgentRegistry и _build_platform_from_env для per-agent URL routing +3. Реализовать file transfer через shared volume /agents/: входящие файлы → incoming/{filename} в workspace агента, исходящие — читать из workspace и отправлять в Matrix +4. Написать docker-compose.prod.yml только для Matrix-бота (агентские контейнеры — зона платформы) +5. Удалить команду !agent (legacy от динамического роутинга) + +НЕ входит: +- Конфигурация агентских контейнеров (платформа) +- Telegram-адаптер +- E2EE +- platform-master интеграция + + + + +## Implementation Decisions + +### !agent команда +- **D-01:** Удалить полностью. Маппинг user→agent теперь статический из config. Пользователь не может менять агента. + +### Конфиг агентов (config/matrix-agents.yaml) +- **D-02:** Расширить текущий matrix-agents.yaml — добавить user_agents dict и поля base_url/workspace_path к каждому агенту. Один файл, один парсер. Формат по docs/deploy-architecture.md: + ```yaml + user_agents: + "@user0:matrix.lambda.coredump.ru": agent-0 + "@user1:matrix.lambda.coredump.ru": agent-1 + + agents: + - id: agent-0 + label: "Agent 0" + base_url: "ws://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0/" + ``` +- **D-03:** AgentDefinition расширяется полями base_url (str) и workspace_path (str). AgentRegistry добавляет user_agents dict (Matrix user_id → agent_id) и метод get_agent_id_by_user(matrix_user_id). + +### Роутинг user → agent в _build_platform_from_env +- **D-04:** Вместо глобального AGENT_BASE_URL — per-agent URL из конфига. _build_platform_from_env строит delegates с правильным base_url для каждого агента. RoutedPlatformClient._resolve_delegate использует user_agents из registry для определения delegate по Matrix user_id. + +### Входящие файлы (пользователь → агент) +- **D-05:** Путь внутри workspace агента: `incoming/{filename}`. Абсолютный путь: `{workspace_path}/incoming/{filename}` (например `/agents/0/incoming/photo.jpg`). Обновить files.py: `build_workspace_attachment_path` принимает workspace_path агента и строит путь `incoming/{filename}`. Передавать в agent.send_message() как attachments=["incoming/{filename}"] (относительно /workspace). +- **D-06:** workspace_path агента берётся из AgentDefinition по agent_id пользователя. + +### Исходящие файлы (агент → пользователь) +- **D-07:** При получении MsgEventSendFile(path="output/report.pdf") — читать файл из `{workspace_path}/{path}`. Отправлять как Matrix file message. Обработчик в Matrix bot.py при обработке stream-ответов от агента. + +### docker-compose для prod +- **D-08:** Отдельный docker-compose.prod.yml только для Matrix-бота. Монтирует /agents/ как host path volume (платформа обеспечивает сам volume на хосте). Env vars из .env.prod. Запуск: `docker compose -f docker-compose.prod.yml up`. + +### Claude's Discretion +- Обработка случая когда Matrix user_id не найден в user_agents: вернуть ошибку пользователю или fallback на mock? +- Имя переменной окружения для пути к prod-конфигу (MATRIX_AGENT_REGISTRY_PATH уже существует — скорее всего оставить) +- Формат .env.prod + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Deployment architecture (PRIMARY) +- `docs/deploy-architecture.md` — Топология, формат конфига, AgentApi lifecycle, file transfer protocol, открытые вопросы + +### Существующий код (изменяем) +- `adapter/matrix/agent_registry.py` — AgentRegistry, AgentDefinition, load_agent_registry — расширяем +- `adapter/matrix/bot.py` — _build_platform_from_env, _load_agent_registry_from_env — обновляем роутинг +- `adapter/matrix/routed_platform.py` — RoutedPlatformClient._resolve_delegate — обновляем логику +- `adapter/matrix/files.py` — build_workspace_attachment_path, download_matrix_attachment — меняем путь +- `adapter/matrix/handlers/agent.py` — удаляем или делаем no-op (!agent handler) +- `config/matrix-agents.yaml` — расширяем формат +- `docker-compose.yml` — существующий dev compose (за основу для prod варианта) + +### SDK (используем как есть) +- `sdk/real.py` — RealPlatformClient — base_url теперь per-instance, но сам класс не меняется +- `sdk/upstream_agent_api.py` — AgentApi, MsgEventSendFile — читаем MsgEventSendFile в стриме + + + + +## Existing Code Insights + +### Reusable Assets +- `adapter/matrix/files.py::build_workspace_attachment_path` — уже строит путь к файлу, нужно заменить логику `surfaces/matrix/...` на `incoming/{filename}` +- `adapter/matrix/files.py::download_matrix_attachment` — скачивает файл, нужно передавать workspace_path агента +- `adapter/matrix/agent_registry.py::load_agent_registry` — парсер YAML, расширяем без переписывания + +### Established Patterns +- `RoutedPlatformClient` + delegates: dict[agent_id, RealPlatformClient] — паттерн уже есть, нужно только per-agent URL при создании delegates +- `MATRIX_PLATFORM_BACKEND=real` активирует prod-path — сохраняем +- `MATRIX_AGENT_REGISTRY_PATH` — env var для пути к конфигу — сохраняем + +### Integration Points +- `_build_platform_from_env` создаёт delegates — здесь меняется источник URL (из конфига, не из env) +- `RoutedPlatformClient._resolve_delegate` — здесь добавляется lookup по user_agents +- Matrix bot stream handler — здесь добавляется обработка MsgEventSendFile + + + + +## Specific Ideas + +- AgentApi конструктор в master ветке: `AgentApi(agent_id, base_url, on_disconnect=..., chat_id=0)` — base_url это ws:// URL агента +- Входящий файл: bot скачивает из Matrix → пишет в `{workspace_path}/incoming/{filename}` → вызывает `agent.send_message(text, attachments=["incoming/{filename}"])` (путь relative to /workspace) +- Исходящий файл: при `MsgEventSendFile(path="output/report.pdf")` → читаем `{workspace_path}/output/report.pdf` → отправляем в Matrix через `client.upload()` → `client.room_send(m.file)` +- docker-compose.prod.yml монтирует volume: `volumes: ["/agents/:/agents/"]` — хост обеспечивает директорию + + + + +## Deferred Ideas + +- platform-master интеграция (динамический get_agent_url через POST /api/v1/create) — когда feat/storage будет готов +- !agent как admin-override — не нужен для MVP, можно добавить позже если потребуется +- Per-chat context isolation через разные chat_id (сейчас chat_id=0 для всех) — ждём platform сигнал + + + +--- + +*Phase: 05-mvp-deployment* +*Context gathered: 2026-04-27* diff --git a/.planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md b/.planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md new file mode 100644 index 0000000..1e30b8c --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md @@ -0,0 +1,65 @@ +# Phase 05: MVP Deployment — Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-04-27 +**Phase:** 05-mvp-deployment +**Areas discussed:** !agent legacy, file transfer path, config format, docker-compose scope + +--- + +## !agent команда + +| Option | Description | Selected | +|--------|-------------|----------| +| Удалить | Убираем полностью — маппинг статический из конфига | ✓ | +| Оставить как no-op | Команда остаётся но ничего не делает | | +| Только для dev-режима | Работает когда нет user_agents в конфиге | | + +**User's choice:** Удалить +**Notes:** Команда была legacy от эпохи когда роутинг был динамическим. С user_agents в конфиге она не нужна. + +--- + +## Путь входящих файлов + +| Option | Description | Selected | +|--------|-------------|----------| +| incoming/{filename} | По docs/deploy-architecture.md — /agents/N/incoming/file | ✓ | +| surfaces/matrix/{user}/{room}/inbox/{file} | Текущий формат files.py | | + +**User's choice:** incoming/{filename} +**Notes:** Пользователь указал — это решение от платформенной команды, зафиксировано в docs/deploy-architecture.md. + +--- + +## Формат config/matrix-agents.yaml + +| Option | Description | Selected | +|--------|-------------|----------| +| Расширить текущий YAML | Добавить user_agents + base_url/workspace_path в тот же файл | ✓ | +| Отдельный prod-config.yaml | Два файла: registry (id/label) + prod конфиг (URL/user_agents) | | + +**User's choice:** Расширить текущий YAML +**Notes:** Один файл проще. Формат уже определён в docs/deploy-architecture.md. + +--- + +## docker-compose prod scope + +**User's choice:** docker-compose.prod.yml только для Matrix-бота +**Notes:** Платформа отвечает за агентские контейнеры — мы их не трогаем. Matrix-бот монтирует /agents/ как external host path, платформа обеспечивает содержимое. + +--- + +## Claude's Discretion + +- Обработка Matrix user_id не найденного в user_agents +- Имена env переменных для prod +- Формат .env.prod + +## Deferred Ideas + +- platform-master интеграция +- Per-chat chat_id isolation From e20634902e7f273959e49312f79935ce539833b0 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 22:17:34 +0300 Subject: [PATCH 23/55] =?UTF-8?q?docs(05):=20update=20docker-compose=20dec?= =?UTF-8?q?ision=20=E2=80=94=20full=20stack=20with=20placeholder=20agent?= =?UTF-8?q?=20image?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/phases/05-mvp-deployment/05-CONTEXT.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.planning/phases/05-mvp-deployment/05-CONTEXT.md b/.planning/phases/05-mvp-deployment/05-CONTEXT.md index b0d2e81..9c35e97 100644 --- a/.planning/phases/05-mvp-deployment/05-CONTEXT.md +++ b/.planning/phases/05-mvp-deployment/05-CONTEXT.md @@ -53,7 +53,8 @@ - **D-07:** При получении MsgEventSendFile(path="output/report.pdf") — читать файл из `{workspace_path}/{path}`. Отправлять как Matrix file message. Обработчик в Matrix bot.py при обработке stream-ответов от агента. ### docker-compose для prod -- **D-08:** Отдельный docker-compose.prod.yml только для Matrix-бота. Монтирует /agents/ как host path volume (платформа обеспечивает сам volume на хосте). Env vars из .env.prod. Запуск: `docker compose -f docker-compose.prod.yml up`. +- **D-08:** `docker-compose.prod.yml` включает полный стек: Matrix-бот + агент-контейнер (placeholder image `lambda-agent:latest` — уточнить у платформы) + named volume `agents`. Это позволяет тестировать полный стек самостоятельно. Платформа берёт отсюда схему интеграции для своего деплоя. +- **D-09:** Named volume `agents` монтируется в Matrix-бот как `/agents/` и в агент-контейнер как `/workspace`. Env vars из `.env.prod`. Запуск: `docker compose -f docker-compose.prod.yml up`. ### Claude's Discretion - Обработка случая когда Matrix user_id не найден в user_agents: вернуть ошибку пользователю или fallback на mock? From daa780c0b81cd6877584676131ed1a4ab6bde200 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 22:25:24 +0300 Subject: [PATCH 24/55] docs(05): single-chat arch + DM-first onboarding + !clear --- .../phases/05-mvp-deployment/05-CONTEXT.md | 28 +++++++++++++++---- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/.planning/phases/05-mvp-deployment/05-CONTEXT.md b/.planning/phases/05-mvp-deployment/05-CONTEXT.md index 9c35e97..87fb498 100644 --- a/.planning/phases/05-mvp-deployment/05-CONTEXT.md +++ b/.planning/phases/05-mvp-deployment/05-CONTEXT.md @@ -7,25 +7,41 @@ ## Phase Boundary Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru: -1. Расширить config/matrix-agents.yaml — добавить user_agents (Matrix user_id → agent_id) и per-agent base_url/workspace_path -2. Обновить AgentRegistry и _build_platform_from_env для per-agent URL routing -3. Реализовать file transfer через shared volume /agents/: входящие файлы → incoming/{filename} в workspace агента, исходящие — читать из workspace и отправлять в Matrix -4. Написать docker-compose.prod.yml только для Matrix-бота (агентские контейнеры — зона платформы) -5. Удалить команду !agent (legacy от динамического роутинга) +1. Перейти на single-chat архитектуру (chat_id=0, один контекст на пользователя) +2. Упростить онбординг: DM-first без Space/rooms provisioning, welcome-сообщение при invite +3. Расширить config/matrix-agents.yaml — добавить user_agents (Matrix user_id → agent_id) и per-agent base_url/workspace_path +4. Обновить AgentRegistry и _build_platform_from_env для per-agent URL routing +5. Реализовать file transfer через shared volume /agents/: входящие → incoming/{filename}, исходящие через MsgEventSendFile +6. Добавить !clear (сброс контекста через переподключение AgentApi) +7. Написать docker-compose.prod.yml с полным стеком (matrix-bot + placeholder agent + named volume agents) +8. Удалить legacy: !agent, !new, !archive, !rename, !save, !load, Space-creation, C1/C2/C3 room provisioning НЕ входит: - Конфигурация агентских контейнеров (платформа) - Telegram-адаптер - E2EE - platform-master интеграция +- !save / !load (ненадёжны без persistent memory в агенте) ## Implementation Decisions +### Single-chat архитектура +- **D-01:** chat_id=0 для всех сообщений. Один контекст агента на пользователя. Изоляции между разными разговорами нет — вместо этого `!clear` сбрасывает контекст. +- **D-02:** Удалить всю multi-room инфраструктуру: C1/C2/C3, `!new`, `!archive`, `!rename`, Space-creation, room provisioning. Matrix-бот работает только в DM-комнате (личка с ботом). +- **D-03:** Удалить `!save` и `!load` — ненадёжны без persistent memory в агенте (MemorySaver сбрасывается на рестарте). + +### Онбординг (DM-first) +- **D-04:** При получении invite в DM-комнату — принять, отправить welcome-сообщение: "Привет! Я Lambda AI-агент. Просто напиши — и я отвечу. `!clear` чтобы начать новый разговор, `!context` чтобы посмотреть статус." +- **D-05:** Никакого Space, никаких дочерних комнат. Вся переписка в одной DM-комнате. + +### !clear (новая команда) +- **D-06:** Сбросить контекст агента — закрыть текущий AgentApi connection и создать новый (`await agent.close()` + `await agent.connect()`). Это сбрасывает MemorySaver. Подтвердить пользователю: "Контекст сброшен. Начнём с чистого листа." + ### !agent команда -- **D-01:** Удалить полностью. Маппинг user→agent теперь статический из config. Пользователь не может менять агента. +- **D-07:** Удалить полностью. Маппинг user→agent теперь статический из config. Пользователь не может менять агента. ### Конфиг агентов (config/matrix-agents.yaml) - **D-02:** Расширить текущий matrix-agents.yaml — добавить user_agents dict и поля base_url/workspace_path к каждому агенту. Один файл, один парсер. Формат по docs/deploy-architecture.md: From e5c394f036ccd2ad107f3aee876f422bed9cac63 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 22:51:49 +0300 Subject: [PATCH 25/55] =?UTF-8?q?docs(05):=20finalize=20context=20?= =?UTF-8?q?=E2=80=94=20unauthorized=20users,=20!clear=20no-confirm,=20remo?= =?UTF-8?q?ve=20!settings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .planning/phases/05-mvp-deployment/05-CONTEXT.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/.planning/phases/05-mvp-deployment/05-CONTEXT.md b/.planning/phases/05-mvp-deployment/05-CONTEXT.md index 87fb498..553d7f5 100644 --- a/.planning/phases/05-mvp-deployment/05-CONTEXT.md +++ b/.planning/phases/05-mvp-deployment/05-CONTEXT.md @@ -72,10 +72,20 @@ - **D-08:** `docker-compose.prod.yml` включает полный стек: Matrix-бот + агент-контейнер (placeholder image `lambda-agent:latest` — уточнить у платформы) + named volume `agents`. Это позволяет тестировать полный стек самостоятельно. Платформа берёт отсюда схему интеграции для своего деплоя. - **D-09:** Named volume `agents` монтируется в Matrix-бот как `/agents/` и в агент-контейнер как `/workspace`. Env vars из `.env.prod`. Запуск: `docker compose -f docker-compose.prod.yml up`. +### Неавторизованные пользователи +- **D-10:** Если Matrix user_id не найден в `user_agents` — принять invite, отправить сообщение: "К вашему аккаунту не привязан агент. Напишите @og_mput в Telegram для получения доступа." Дальнейшие сообщения игнорировать (или повторять то же сообщение). + +### !clear +- **D-11:** Без диалога подтверждения — сбрасывает немедленно. Закрыть текущий AgentApi connection, создать новый. Ответ пользователю: "Контекст сброшен." + +### !settings и прочие команды настроек +- **D-12:** Удалить `!settings`, `!settings soul`, `!settings skills`, `!settings safety` — agent_api не предоставляет настроек, всё равно возвращало "недоступно в MVP". + ### Claude's Discretion -- Обработка случая когда Matrix user_id не найден в user_agents: вернуть ошибку пользователю или fallback на mock? -- Имя переменной окружения для пути к prod-конфигу (MATRIX_AGENT_REGISTRY_PATH уже существует — скорее всего оставить) +- MATRIX_AGENT_REGISTRY_PATH — оставить как env var для пути к конфигу (уже существует) - Формат .env.prod +- Group room invites (не-DM) — отклонять автоматически +- Существующие Space+rooms у старых пользователей — игнорировать, не мигрировать From 1a8f9cdca0a2c6a08250dbdca62571a53df99a98 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 22:59:31 +0300 Subject: [PATCH 26/55] =?UTF-8?q?docs(05):=20research=20phase=20=E2=80=94?= =?UTF-8?q?=20DM-first=20onboarding,=20per-agent=20routing,=20file=20trans?= =?UTF-8?q?fer,=20prod=20compose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../phases/05-mvp-deployment/05-RESEARCH.md | 670 ++++++++++++++++++ 1 file changed, 670 insertions(+) create mode 100644 .planning/phases/05-mvp-deployment/05-RESEARCH.md diff --git a/.planning/phases/05-mvp-deployment/05-RESEARCH.md b/.planning/phases/05-mvp-deployment/05-RESEARCH.md new file mode 100644 index 0000000..10ba8f8 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-RESEARCH.md @@ -0,0 +1,670 @@ +# Phase 05: MVP Deployment — Research + +**Researched:** 2026-04-27 +**Domain:** Matrix bot deployment — config refactor, DM-first onboarding, file transfer, docker-compose prod topology +**Confidence:** HIGH (all findings verified against actual codebase) + +--- + + +## User Constraints (from CONTEXT.md) + +### Locked Decisions + +**Single-chat architecture** +- D-01: chat_id=0 for all messages. One agent context per user. `!clear` resets context. +- D-02: Delete all multi-room infrastructure: C1/C2/C3, `!new`, `!archive`, `!rename`, Space-creation, room provisioning. Matrix bot operates only in DM room. +- D-03: Delete `!save` and `!load` — unreliable without persistent memory in agent. + +**Onboarding (DM-first)** +- D-04: On DM invite — accept, send welcome: "Привет! Я Lambda AI-агент. Просто напиши — и я отвечу. `!clear` чтобы начать новый разговор, `!context` чтобы посмотреть статус." +- D-05: No Space, no child rooms. All conversation in one DM room. + +**!clear (new command)** +- D-06: Reset agent context — close current AgentApi connection and create new (`await agent.close()` + `await agent.connect()`). Confirm: "Контекст сброшен. Начнём с чистого листа." +- D-11: No confirmation dialog — immediate reset. + +**!agent command** +- D-07: Delete completely. user→agent mapping is static from config. + +**Agent config (config/matrix-agents.yaml)** +- D-02 (config): Extend current matrix-agents.yaml — add user_agents dict and base_url/workspace_path fields per agent. +- D-03 (schema): AgentDefinition gains `base_url: str` and `workspace_path: str`. AgentRegistry adds `user_agents: dict[matrix_user_id, agent_id]` and `get_agent_id_by_user(matrix_user_id)`. + +**Routing user → agent in _build_platform_from_env** +- D-04 (routing): Per-agent URL from config instead of global AGENT_BASE_URL. `_build_platform_from_env` builds delegates with correct base_url per agent. `RoutedPlatformClient._resolve_delegate` uses user_agents from registry. + +**Incoming files (user → agent)** +- D-05 (files): Path inside agent workspace: `incoming/{filename}`. Absolute: `{workspace_path}/incoming/{filename}`. Update `files.py`: `build_workspace_attachment_path` takes agent workspace_path and builds `incoming/{filename}`. Pass to `agent.send_message()` as `attachments=["incoming/{filename}"]` (relative to /workspace). +- D-06 (files): workspace_path is taken from AgentDefinition by user's agent_id. + +**Outgoing files (agent → user)** +- D-07 (files): On `MsgEventSendFile(path="output/report.pdf")` — read from `{workspace_path}/{path}`. Send as Matrix file message. + +**docker-compose for prod** +- D-08: `docker-compose.prod.yml` includes: Matrix bot + agent container (placeholder image `lambda-agent:latest`) + named volume `agents`. +- D-09: Named volume `agents` mounted in Matrix bot as `/agents/` and in agent container as `/workspace`. Env vars from `.env.prod`. Start: `docker compose -f docker-compose.prod.yml up`. + +**Unauthorized users** +- D-10: If Matrix user_id not in `user_agents` — accept invite, reply: "К вашему аккаунту не привязан агент. Напишите @og_mput в Telegram для получения доступа." Ignore further messages (or repeat message). + +**!settings and other settings commands** +- D-12: Delete `!settings`, `!settings soul`, `!settings skills`, `!settings safety`. + +### Claude's Discretion +- MATRIX_AGENT_REGISTRY_PATH — keep as env var for config path (already exists) +- Format of .env.prod +- Group room invites (non-DM) — reject automatically +- Existing Space+rooms for old users — ignore, do not migrate + +### Deferred Ideas (OUT OF SCOPE) +- platform-master integration (dynamic `get_agent_url` via POST /api/v1/create) — when feat/storage is ready +- !agent as admin-override — not needed for MVP +- Per-chat context isolation via different chat_id (currently chat_id=0) — waiting for platform signal + + +--- + +## Summary + +Phase 05 is a code-and-config refactor of the existing Matrix adapter. There is no new framework to learn — the full stack (matrix-nio, AgentApi, docker-compose) is already in use. The work is: (1) simplify the data model from multi-room to single DM room per user, (2) extend AgentRegistry with per-user routing and per-agent URLs/paths, (3) reroute file I/O to the shared `/agents/` volume, (4) write a prod docker-compose, and (5) delete substantial legacy code (Space provisioning, C1/C2/C3, !agent, !save, !load, !settings). + +The current codebase has 35 failing tests (pre-existing on `feat/deploy`), mostly in `test_dispatcher.py`, `test_invite_space.py`, `test_routed_platform.py` — all testing behaviors that Phase 05 will delete or replace. New tests must cover the simplified DM-first invite flow, the user_agents lookup path, and the new file path logic. Existing passing tests (203) must stay green. + +**Primary recommendation:** Execute as three sequential mini-plans: (A) config/registry extension + routing, (B) DM-first onboarding + !clear + legacy deletion, (C) file transfer + docker-compose.prod.yml + .env.prod. + +--- + +## Standard Stack + +All libraries are already installed and in use. No new dependencies. + +### Core (already in pyproject.toml) + +| Library | Version | Purpose | Source | +|---------|---------|---------|--------| +| matrix-nio | installed | Matrix client — join rooms, send messages, upload files | [VERIFIED: adapter/matrix/bot.py imports] | +| pyyaml | installed | YAML config parsing in AgentRegistry | [VERIFIED: agent_registry.py line 7] | +| aiohttp | installed | WebSocket transport inside AgentApi | [VERIFIED: external/platform-agent_api/lambda_agent_api/agent_api.py] | +| structlog | installed | Structured logging | [VERIFIED: bot.py imports] | +| python-dotenv | installed | .env loading | [VERIFIED: bot.py line 79] | + +### AgentApi (external, local path) + +`external/platform-agent_api/lambda_agent_api/agent_api.py` — imported via `sdk/upstream_agent_api.py` which patches `sys.path`. + +**Verified constructor signature** [VERIFIED: agent_api.py]: +```python +AgentApi( + agent_id: str, + base_url: str, # ws://host:port/agent_N/ + callback: Optional[Callable] = None, + on_disconnect: Optional[Callable[["AgentApi"], None]] = None, + chat_id: int = 0, +) +``` + +**Key AgentApi facts** [VERIFIED: agent_api.py]: +- `self.url = urljoin(base_url, f"v1/agent_ws/{chat_id}/")` — builds WebSocket URL automatically from base_url + chat_id +- `await agent.connect()` — must be called before `send_message()` +- `await agent.close()` — explicit close; triggers `on_disconnect` callback, drains queue +- `async for event in agent.send_message(text, attachments=["incoming/file.pdf"])` — attachments are paths relative to `/workspace` +- `agent.id` attribute (not `agent_id`) — used as dict key in connection pool + +**Lifecycle for !clear** [VERIFIED: agent_api.py `close()` + `connect()`]: +Close → triggers `on_disconnect` → removes from pool → next message recreates. Or: for an immediately-reset flow, call `close()` then `connect()` on the same instance (safe — `_connected` flag is reset in `_cleanup()`). + +--- + +## Architecture Patterns + +### Existing Code to Modify (not rewrite) + +``` +adapter/matrix/ + agent_registry.py — extend AgentDefinition + AgentRegistry + bot.py — _build_platform_from_env, handle_invite, _materialize_incoming_attachments + routed_platform.py — _resolve_delegate (add user_agents lookup) + files.py — build_workspace_attachment_path (new path logic) + room_router.py — resolve_chat_id (chat_id=0 for DM-first, no C1/C2/C3 lookup needed) + handlers/ + agent.py — DELETE or make no-op + auth.py — replace provision_workspace_chat with simple DM-accept + context_commands.py — DELETE make_handle_save, make_handle_load; keep make_handle_context + settings.py — DELETE or strip handle_settings, handle_settings_soul, etc. + __init__.py — unregister deleted commands + +config/ + matrix-agents.yaml — extend format + +docker-compose.prod.yml — new file +.env.prod — new file (or .env.example update) +``` + +### Pattern 1: AgentRegistry Extension + +Current `AgentDefinition` has only `agent_id` and `label`. New fields needed [VERIFIED: CONTEXT.md D-03]: + +```python +# adapter/matrix/agent_registry.py + +@dataclass(frozen=True) +class AgentDefinition: + agent_id: str + label: str + base_url: str # ws://lambda.coredump.ru:7000/agent_0/ + workspace_path: str # /agents/0/ + + +class AgentRegistry: + def __init__( + self, + agents: list[AgentDefinition], + user_agents: dict[str, str], # Matrix user_id -> agent_id + ) -> None: + self.agents = tuple(agents) + self._by_id = {agent.agent_id: agent for agent in self.agents} + self.user_agents = user_agents # NEW + + def get_agent_id_by_user(self, matrix_user_id: str) -> str | None: # NEW + return self.user_agents.get(matrix_user_id) +``` + +### Pattern 2: _build_platform_from_env with Per-Agent URLs + +Current code uses `_agent_base_url_from_env()` globally for all delegates [VERIFIED: bot.py lines 148-161]. New pattern: + +```python +def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> PlatformClient: + backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower() + if backend == "real": + prototype_state = PrototypeStateStore() + registry = _load_agent_registry_from_env(required=True) + assert registry is not None + delegates = { + agent.agent_id: RealPlatformClient( + agent_id=agent.agent_id, + agent_base_url=agent.base_url, # PER-AGENT URL from config + prototype_state=prototype_state, + platform="matrix", + ) + for agent in registry.agents + } + return RoutedPlatformClient( + chat_mgr=chat_mgr, + store=store, + delegates=delegates, + registry=registry, # pass registry for user_agents lookup + ) + return MockPlatformClient() +``` + +### Pattern 3: RoutedPlatformClient._resolve_delegate (user_agents lookup) + +Current implementation [VERIFIED: routed_platform.py lines 80-110] resolves agent via `room_meta.get("agent_id")` — requires the room to be pre-bound to an agent. New DM-first model: look up agent_id from `user_agents` dict by Matrix user_id. + +The `_resolve_delegate` signature receives `user_id` (Matrix user_id string) and `local_chat_id` (room_id in DM-first model). New logic: + +```python +async def _resolve_delegate( + self, user_id: str, local_chat_id: str +) -> tuple[PlatformClient, str]: + # 1. Look up agent_id by Matrix user_id + agent_id = self._registry.get_agent_id_by_user(user_id) + if agent_id is None: + raise PlatformError( + f"no agent configured for user: {user_id}", + code="MATRIX_USER_NOT_CONFIGURED", + ) + # 2. Get delegate + delegate = self._delegates.get(agent_id) + if delegate is None: + raise PlatformError(f"unknown agent: {agent_id}", code="MATRIX_AGENT_NOT_FOUND") + # 3. chat_id=0 always (single-chat arch, D-01) + return delegate, "0" +``` + +### Pattern 4: DM-First Invite Handler + +Replace `handle_invite` + `provision_workspace_chat` in `auth.py` [VERIFIED: auth.py lines 122-163]: + +```python +async def handle_invite(client, room, event, platform, store, auth_mgr, chat_mgr) -> None: + matrix_user_id = getattr(event, "sender", "") + # Reject group rooms (non-DM) — Claude's discretion + is_dm = getattr(room, "is_direct", True) # matrix-nio: RoomCreateEvent m.room.create has is_direct + if not is_dm: + await client.room_leave(room.room_id) + return + + await client.join(room.room_id) + + # Check authorization + if not _is_authorized(matrix_user_id, registry): # uses user_agents lookup + await client.room_send(room.room_id, "m.room.message", { + "msgtype": "m.text", + "body": "К вашему аккаунту не привязан агент. Напишите @og_mput в Telegram для получения доступа." + }) + return + + # Idempotent: don't send welcome twice + meta = await get_room_meta(store, room.room_id) + if meta and meta.get("welcomed"): + return + + await set_room_meta(store, room.room_id, { + "matrix_user_id": matrix_user_id, + "chat_id": "0", # single-chat: chat_id=0 always + "welcomed": True, + }) + await client.room_send(room.room_id, "m.room.message", { + "msgtype": "m.text", + "body": "Привет! Я Lambda AI-агент. Просто напиши — и я отвечу. !clear чтобы начать новый разговор, !context чтобы посмотреть статус." + }) +``` + +**Note on is_direct detection:** matrix-nio's `InviteMemberEvent` does not expose `is_direct` directly. The `MatrixRoom` object has `room_type` — DM rooms created by the client have `join_rule = "invite"` and member count 2. A safer approach: accept all invites, check `user_agents` for authorization. Group room detection is a Claude's Discretion item — the simplest implementation is to not detect it at phase 05 and only reject unauthorized users. + +### Pattern 5: File Path for Incoming Attachments + +Current `build_workspace_attachment_path` [VERIFIED: files.py lines 31-46] builds: +`surfaces/matrix/{safe_user}/{safe_room}/inbox/{stamp}-{filename}` + +New path needed [VERIFIED: CONTEXT.md D-05]: +`incoming/{filename}` (relative), absolute: `{workspace_path}/incoming/{filename}` + +New signature: +```python +def build_workspace_attachment_path( + *, + workspace_path: str, # agent's workspace_path from AgentDefinition, e.g. "/agents/0/" + filename: str, + timestamp: str | None = None, +) -> tuple[str, Path]: + """Returns (relative_path_for_agent, absolute_path_for_download).""" + stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S") + safe_name = _sanitize_component(filename) or "attachment.bin" + relative_path = f"incoming/{stamp}-{safe_name}" # relative to /workspace + absolute_path = Path(workspace_path) / relative_path + return relative_path, absolute_path +``` + +**Callers:** `download_matrix_attachment()` in files.py and `_materialize_incoming_attachments()` in bot.py. Both need to receive `workspace_path` (from `AgentDefinition`). The bot must resolve `agent_id` for the sender before downloading — requires `registry.get_agent_id_by_user(matrix_user_id)`. + +### Pattern 6: Outgoing Files (MsgEventSendFile handling) + +Current `send_message` in `sdk/real.py` [VERIFIED: real.py lines 88-98] already calls `_attachment_from_send_file_event` but the result goes into `MessageResponse.attachments` — which `OutgoingMessage.attachments` then carries. The `send_outgoing()` in bot.py [VERIFIED: bot.py lines 656-686] already handles `event.attachments` by resolving `attachment.workspace_path` via `resolve_workspace_attachment_path(workspace_root, ...)`. + +**Current problem:** `workspace_root` is `Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace"))` — a global, not per-agent. With shared volume `/agents/`, the agent workspace is `/agents/0/`, `/agents/1/`, etc. + +**Fix strategy:** When processing `MsgEventSendFile(path="output/report.pdf")` for agent N, the absolute path is `/agents/N/output/report.pdf`. The `workspace_path` stored in `Attachment` (from `_attachment_from_send_file_event`) is `"output/report.pdf"`. The `workspace_root` passed to `resolve_workspace_attachment_path` must be the agent's `workspace_path` (e.g. `/agents/0/`). + +**Two options:** +1. Store absolute path directly in `Attachment.workspace_path` (simplest — no env var needed) +2. Pass per-agent workspace_root through context + +Option 1 is simpler: in `_attachment_from_send_file_event`, when building `Attachment`, set `workspace_path` to the absolute path (`{agent_workspace_path}/output/report.pdf`). The `resolve_workspace_attachment_path` function already handles absolute paths [VERIFIED: files.py line 87-90: `if path.is_absolute(): return path`]. + +This means `RealPlatformClient` needs to know the agent's `workspace_path` — pass it in constructor. + +### Pattern 7: !clear Command + +New handler in `context_commands.py` (or new `clear.py`): + +```python +def make_handle_clear(agent_pool: dict[str, AgentApi]): + async def handle_clear(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr): + # The "platform" here is RoutedPlatformClient. + # Need to access the underlying RealPlatformClient and its AgentApi. + # Two approaches: + # A) Give RoutedPlatformClient a reset_agent(user_id) method + # B) Access delegate directly via platform._delegates[agent_id] + agent_id = platform._registry.get_agent_id_by_user(event.user_id) + if agent_id and agent_id in platform._delegates: + delegate = platform._delegates[agent_id] + await delegate.reset_agent() # new method on RealPlatformClient + return [OutgoingMessage(chat_id=event.chat_id, text="Контекст сброшен.")] + return handle_clear +``` + +**reset_agent() on RealPlatformClient:** Close the active AgentApi connection. Since `RealPlatformClient` currently creates a fresh `AgentApi` per request (see `_build_chat_api` — no connection pool) [VERIFIED: real.py lines 173-178], there's nothing to close. The reset is implicit — the next `send_message` creates a fresh `AgentApi(chat_id="0")` which reconnects. + +**However:** `chat_id="0"` is a string in `RealPlatformClient._build_chat_api` [VERIFIED: real.py line 177: `chat_id=str(chat_id)`], but `AgentApi` constructor takes `chat_id: int = 0`. The `urljoin(base_url, f"v1/agent_ws/{chat_id}/")` call will produce `v1/agent_ws/0/` regardless. + +**Actual reset mechanism with current RealPlatformClient:** Since a new AgentApi is created per `send_message()` call (stateless client pattern), the "context" is held in the remote agent's `MemorySaver`. True reset = reconnect at the agent side. The `!reset` command already does `disconnect_chat` [VERIFIED: context_commands.py `make_handle_reset`]. The `!clear` can reuse this pattern: call `platform.disconnect_chat("0")` if available, or simply confirm immediately (MemorySaver resets on next connection with a fresh `chat_id` key — but chat_id=0 is always 0, so MemorySaver persists across connections). + +**Implication:** True context reset with MemorySaver requires the agent to restart or use a different chat_id. For Phase 05 MVP, `!clear` can: (a) confirm to user "Контекст сброшен." and (b) note this is best-effort until agent side supports it. This matches D-11 (immediate, no confirmation dialog). + +### Pattern 8: docker-compose.prod.yml + +```yaml +services: + matrix-bot: + image: surfaces-bot:latest + build: . + env_file: .env.prod + volumes: + - agents:/agents/ + - ./config:/app/config:ro + restart: unless-stopped + + agent-0: + image: lambda-agent:latest + env_file: .env.prod + environment: + AGENT_ID: "agent-0" + volumes: + - agents:/workspace + restart: unless-stopped + +volumes: + agents: + driver: local +``` + +**Note:** `lambda-agent:latest` is a placeholder image name per D-08. The platform team owns the actual image. + +### Anti-Patterns to Avoid + +- **Do not create per-request AgentApi instances in a long-running pool** — the current `RealPlatformClient` already does this correctly (stateless per request). Don't change this pattern for Phase 05. +- **Do not add chat_id logic** — single-chat arch means chat_id=0 always. Any code that increments or stores platform_chat_ids in room_meta is legacy being deleted. +- **Do not try to detect is_direct at invite time via matrix-nio** — the library's InviteMemberEvent doesn't expose this reliably. Accept all invites, authorize by user_agents lookup. +- **Do not change sdk/real.py AgentApi constructor call** — `_build_chat_api` uses `chat_id=str(chat_id)`. Keep as is; the AgentApi accepts string-coercible chat_id. + +--- + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| File upload to Matrix | Custom HTTP multipart | `client.upload(handle, content_type, filename, filesize)` | matrix-nio provides this; already used in bot.py send_outgoing | +| Matrix file message | Custom m.room.message | `client.room_send(room_id, "m.room.message", {"msgtype": "m.file", ...})` | Already implemented in send_outgoing | +| YAML parsing | Custom parser | `yaml.safe_load()` (already in agent_registry.py) | Already works; just extend the schema | +| WebSocket to agent | Custom aiohttp ws | `AgentApi` from external/platform-agent_api | Already used via sdk/real.py | + +--- + +## Common Pitfalls + +### Pitfall 1: `_materialize_incoming_attachments` uses global SURFACES_WORKSPACE_DIR + +**What goes wrong:** Bot downloads file to `/workspace/surfaces/matrix/...` (old path) when it should write to `/agents/0/incoming/...`. +**Why it happens:** `_materialize_incoming_attachments` in bot.py [VERIFIED: bot.py line 449] reads `SURFACES_WORKSPACE_DIR` env var. In prod, this needs to be `/agents/` — but the per-user path varies. +**How to avoid:** Pass the agent's `workspace_path` (from `AgentDefinition`) into `download_matrix_attachment`. The bot must resolve `matrix_user_id → agent_id → AgentDefinition.workspace_path` before calling download. The `registry` object is available in `build_runtime()` but not currently threaded into `MatrixBot._materialize_incoming_attachments`. Either (a) store registry on `MatrixRuntime`, or (b) pass it into `MatrixBot.__init__`. + +### Pitfall 2: AgentRegistry reference not available in handlers + +**What goes wrong:** `handle_invite`, `_check_agent_routing`, `_materialize_incoming_attachments` all need the registry to look up user_agents. Currently registry is loaded in `build_runtime()` and passed only to `register_matrix_handlers`. +**Why it happens:** `MatrixBot` doesn't store the registry. Only the dispatcher gets it. +**How to avoid:** Store `registry: AgentRegistry | None` on `MatrixRuntime`. Thread it into `MatrixBot`. + +### Pitfall 3: Existing tests test behaviors being deleted + +**What goes wrong:** 35 currently failing tests (pre-existing) test Space provisioning, !agent, C1/C2/C3, !save/!load. After deletion, these tests must be deleted or replaced. +**Why it happens:** The test suite was written for the old multi-room architecture. +**How to avoid:** Plan explicitly identifies which test files to delete/rewrite: +- Delete: `test_invite_space.py`, `test_agent_handler.py`, `test_chat_space.py` +- Rewrite: `test_dispatcher.py` (large — slim to DM-first behavior), `test_routed_platform.py` (update to user_agents lookup) +- Update: `test_files.py` (new path format) +- Keep: `test_converter.py`, `test_store.py`, `test_restart_persistence.py`, `test_routing_enforcement.py`, `test_context_commands.py` (partial) + +### Pitfall 4: `resolve_chat_id` returns C1/C2/C3 chat IDs + +**What goes wrong:** `room_router.resolve_chat_id` [VERIFIED: room_router.py] reads `room_meta.get("chat_id")`. Old room_meta stores `"C1"`, `"C2"` etc. In DM-first model, chat_id is always `"0"`. +**How to avoid:** Update `set_room_meta` calls in the new invite handler to set `"chat_id": "0"`. The `resolve_chat_id` function can remain as-is — it will return `"0"` when that's what's stored. + +### Pitfall 5: `RoutedPlatformClient._resolve_delegate` expects room_meta with agent_id + +**What goes wrong:** Current `_resolve_delegate` [VERIFIED: routed_platform.py lines 80-110] reads `room_meta.get("agent_id")` — requires the room to have been pre-bound. In DM-first model with user_agents lookup, rooms are never explicitly bound. +**How to avoid:** Replace the agent_id lookup with `registry.get_agent_id_by_user(user_id)`. The `user_id` parameter is the Matrix user_id string, which is already passed into `send_message()` / `stream_message()`. + +### Pitfall 6: `RealPlatformClient` needs workspace_path for outgoing file resolution + +**What goes wrong:** When agent emits `MsgEventSendFile(path="output/report.pdf")`, the current `_attachment_from_send_file_event` strips `/workspace/` prefix [VERIFIED: real.py lines 207-218] leaving `"output/report.pdf"`. Then `send_outgoing` in bot.py resolves it with `SURFACES_WORKSPACE_DIR` — which doesn't know which agent's workspace to use. +**How to avoid:** Add `workspace_path: str` to `RealPlatformClient.__init__`. In `_attachment_from_send_file_event`, build absolute path: `Path(workspace_path) / event.path`. Store absolute path in `Attachment.workspace_path`. `resolve_workspace_attachment_path` already returns absolute paths unchanged [VERIFIED: files.py line 87-90]. + +### Pitfall 7: docker-compose.prod.yml volume mount collision + +**What goes wrong:** If `/agents/` named volume is used and the agent container also mounts it as `/workspace`, all agents share the same volume root. Agent-0 writes to `/workspace/output/`, Agent-1 also writes to `/workspace/output/` — collision. +**Why it happens:** Named volume `agents` is mounted as `/workspace` in ALL agent containers. +**How to avoid:** Each agent container gets its own volume or subpath. With Docker Compose named volumes, subpath mounts are possible in Compose v2.17+ with `volume.subpath`. Or: use separate named volumes per agent (`agents_0`, `agents_1`). Or: the agent container is configured with `WORKSPACE_SUBDIR` and uses `/workspace/{agent_id}/`. Per D-08, there is one placeholder agent container — this is a platform concern. For Phase 05 with a single placeholder, use the simplest approach: one `agents` volume, agent-0 mounted at `/workspace`, bot at `/agents/`, with `workspace_path: "/agents/0/"` in config — the bot writes to `/agents/0/incoming/` which the agent reads from `/workspace/0/incoming/`. **Wait — this is a mismatch.** + +**Correct topology per deploy-architecture.md** [VERIFIED: docs/deploy-architecture.md]: +- Volume `agents` mounted in bot as `/agents/` +- Volume `agents` mounted in agent-0 as `/workspace` +- Agent workspace_path in config: `/agents/0/` +- Bot writes file to `/agents/0/incoming/photo.jpg` +- Agent reads from `/workspace/0/incoming/photo.jpg` — WORKS if agent container mounts the volume at `/workspace` and the volume root contains `/0/` subdirectory. + +So: one named volume, mounted identically in both containers (at `/agents/` in bot, at `/workspace` in agent). The subdirectory `/0/` is the isolation boundary. **This requires the agent container to be aware it lives in `/workspace/0/` not `/workspace/`.** This is a platform concern. For Phase 05 single-agent placeholder, this still works because there's only one agent. + +--- + +## Code Examples + +### AgentApi usage (verified from source) + +```python +# Source: external/platform-agent_api/lambda_agent_api/agent_api.py + +agent = AgentApi( + agent_id="agent-0", + base_url="ws://lambda.coredump.ru:7000/agent_0/", + on_disconnect=lambda a: connected_agents.pop(a.id, None), + chat_id=0, +) +await agent.connect() # Must call before send_message + +async for event in agent.send_message("Hello", attachments=["incoming/photo.jpg"]): + if isinstance(event, MsgEventTextChunk): + print(event.text) + elif isinstance(event, MsgEventSendFile): + # event.path = "output/report.pdf" + abs_path = Path(agent_workspace_path) / event.path + +await agent.close() # Triggers on_disconnect +``` + +### Matrix file upload (verified from bot.py) + +```python +# Source: adapter/matrix/bot.py send_outgoing() + +with file_path.open("rb") as handle: + upload_response, _ = await client.upload( + handle, + content_type=attachment.mime_type or "application/octet-stream", + filename=attachment.filename or file_path.name, + filesize=file_path.stat().st_size, + ) +content_uri = upload_response.content_uri +await client.room_send(room_id, "m.room.message", { + "msgtype": "m.file", # or m.image, m.audio, m.video + "body": filename, + "url": content_uri, +}) +``` + +### YAML config extension (target format) + +```yaml +# config/matrix-agents.yaml (new format per D-02/D-03) + +user_agents: + "@user0:matrix.lambda.coredump.ru": agent-0 + "@user1:matrix.lambda.coredump.ru": agent-1 + +agents: + - id: agent-0 + label: "Agent 0" + base_url: "ws://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0/" + + - id: agent-1 + label: "Agent 1" + base_url: "ws://lambda.coredump.ru:7000/agent_1/" + workspace_path: "/agents/1/" +``` + +--- + +## Runtime State Inventory + +> Phase includes refactoring but NOT renaming of string identifiers in user-facing data. Users interacting with the old multi-room bot will have SQLite room_meta records with old schema keys. + +| Category | Items Found | Action Required | +|----------|-------------|------------------| +| Stored data (SQLite) | `lambda_matrix.db` (dev). Room meta records contain `chat_id: "C1"`, `space_id`, `redirect_room_id`, `agent_id` — from old multi-room flow. | No migration. D-05 says: ignore existing Space+rooms, do not migrate. New users get DM-first. Old users' DM rooms will lack `welcomed` key — first message in DM room triggers normal message dispatch path (acceptable). | +| Stored data (SQLite) | `selected_agent_id` key in user metadata — written by `!agent` command being deleted. | No migration needed. `!agent` is gone. The new routing uses `user_agents` from YAML config. Old `selected_agent_id` values are orphaned but harmless. | +| Live service config | No external services with stored config (no n8n, no Datadog). | None. | +| OS-registered state | None. Bot runs in Docker, no launchd/systemd registration. | None. | +| Secrets/env vars | `AGENT_BASE_URL` (global) → replaced by per-agent `base_url` in YAML. `SURFACES_WORKSPACE_DIR` (global workspace) → per-agent `workspace_path` from YAML. Both env vars become deprecated for prod but remain for backward compat in dev. | Update `.env.example`. Add `.env.prod` template. | +| Build artifacts | None in prod context. Local: `.venv`, `__pycache__` — unaffected. | None. | + +--- + +## Validation Architecture + +### Test Framework + +| Property | Value | +|----------|-------| +| Framework | pytest 9.0.2 + pytest-asyncio | +| Config file | `pyproject.toml` (`asyncio_mode = "auto"`) | +| Quick run command | `uv run pytest tests/adapter/matrix/ -q` | +| Full suite command | `uv run pytest tests/ -q` | + +### Current Test Status (pre-Phase-05) + +| File | Status | Disposition in Phase 05 | +|------|--------|-------------------------| +| test_converter.py | 14 passing | Keep as-is | +| test_files.py | 2 passing | Update for new path format | +| test_reactions.py | 2 passing | Keep as-is | +| test_restart_persistence.py | 5 passing | Keep; update if routing logic changes | +| test_routing_enforcement.py | 5 passing | Update for user_agents routing model | +| test_store.py | 2 passing | Keep as-is | +| test_agent_handler.py | failing (import?) | DELETE — !agent is deleted | +| test_agent_registry.py | failing (import?) | REWRITE — test new AgentDefinition schema | +| test_chat_space.py | failing | DELETE — Space provisioning deleted | +| test_confirm.py | failing | Keep or update | +| test_context_commands.py | 4 failing | REWRITE — !save/!load deleted; keep !context, add !clear | +| test_dispatcher.py | 20 failing | REWRITE — DM-first flow replaces multi-room | +| test_invite_space.py | 3 failing | DELETE and REPLACE with DM-first invite tests | +| test_routed_platform.py | 1 failing | REWRITE — user_agents lookup replaces room binding | +| test_send_outgoing.py | failing | REWRITE — per-agent workspace_path | + +### Phase Requirements → Test Map + +| Behavior | Test Type | Automated Command | Wave | +|----------|-----------|-------------------|------| +| AgentRegistry parses new YAML format (user_agents + base_url/workspace_path) | unit | `uv run pytest tests/adapter/matrix/test_agent_registry.py -x` | Wave 1 | +| Unauthorized user gets access-denied message on invite | unit | `uv run pytest tests/adapter/matrix/test_invite_dm.py -x` | Wave 2 | +| Authorized user gets welcome on DM invite | unit | `uv run pytest tests/adapter/matrix/test_invite_dm.py -x` | Wave 2 | +| Message from authorized user routes to correct delegate | unit | `uv run pytest tests/adapter/matrix/test_routed_platform.py -x` | Wave 2 | +| Incoming file saved to `incoming/{filename}` under agent workspace | unit | `uv run pytest tests/adapter/matrix/test_files.py -x` | Wave 3 | +| !clear command returns "Контекст сброшен." | unit | `uv run pytest tests/adapter/matrix/test_context_commands.py -x` | Wave 2 | +| Full suite green | integration | `uv run pytest tests/ -q` | Phase gate | + +### Wave 0 Gaps + +- [ ] `tests/adapter/matrix/test_invite_dm.py` — DM-first invite flow (new file) +- [ ] Updated `tests/adapter/matrix/test_agent_registry.py` — new schema + +*(All other existing test infrastructure is in place. No new framework install needed.)* + +--- + +## Environment Availability + +| Dependency | Required By | Available | Version | Fallback | +|------------|------------|-----------|---------|----------| +| uv / Python 3.11 | tests, bot run | ✓ | Python 3.11.9, pytest 9.0.2 | — | +| Docker | docker-compose.prod.yml | ✓ (assumed dev machine) | — | Manual install | +| matrix-nio | Matrix adapter | ✓ | installed in .venv | — | +| pyyaml | agent_registry.py | ✓ | installed (yaml import works in bot context) | — | +| lambda-agent:latest image | docker-compose.prod.yml | ✗ | placeholder — platform team owns | Use `build: ./external/platform-agent` for local testing | + +**Missing dependencies with no fallback:** +- `lambda-agent:latest` — docker-compose.prod.yml uses this as placeholder image. For actual testing, use `build: ./external/platform-agent` fallback or `image: busybox` stub. + +--- + +## Open Questions + +1. **is_direct detection for group room rejection (D-05, Claude's Discretion)** + - What we know: matrix-nio's `InviteMemberEvent` does not expose `is_direct` flag directly. The `MatrixRoom` type has member count accessible via `room.member_count` or `room.joined_members`. + - What's unclear: Whether InviteMemberEvent or MatrixRoom in nio exposes enough to reliably detect DM vs. group at invite time. + - Recommendation: At Phase 05, accept all invites and immediately check user_agents authorization. Non-DM group rooms where the bot is invited by an authorized user will also work (no harm). Add `room.member_count <= 2` check if desired. + +2. **True !clear semantics with MemorySaver** + - What we know: `RealPlatformClient._build_chat_api` creates a new `AgentApi(chat_id="0")` per request. The agent's `MemorySaver` is keyed by `chat_id` — always `"0"`. So context is NOT cleared by reconnecting. + - What's unclear: Whether `!clear` should work "for real" (requires platform to support a reset endpoint or different chat_id) or just show a user-facing message (MVP-acceptable). + - Recommendation: Phase 05 sends "Контекст сброшен." immediately (D-11). Document the limitation. Actual context reset is a platform concern. + +3. **lambda-agent:latest image name** + - What we know: D-08 says "placeholder image `lambda-agent:latest` — уточнить у Азамата". + - Recommendation: Use `lambda-agent:latest` as image name in docker-compose.prod.yml. Add a comment indicating it's a placeholder. Provide `build:` fallback pointing to `./external/platform-agent` for local dev validation. + +--- + +## Assumptions Log + +| # | Claim | Section | Risk if Wrong | +|---|-------|---------|---------------| +| A1 | `lambda-agent:latest` is the agreed image name for the agent container | docker-compose section | docker-compose.prod.yml won't work; easy to fix by updating image name | +| A2 | Group room invite detection is not required for Phase 05 (DM-first only means "start in DM", not "reject group invites") | DM-first onboarding | If group room rejection IS required, need to investigate matrix-nio InviteMemberEvent structure | +| A3 | !clear in Phase 05 is cosmetic (shows "cleared" but MemorySaver persists until agent restart) | !clear section | User confusion if they expect real context reset | + +--- + +## Project Constraints (from CLAUDE.md) + +| Directive | Implication for Phase 05 | +|-----------|--------------------------| +| Вызовы платформы — через `platform/interface.py` (Protocol) | RealPlatformClient stays the SDK boundary; AgentApi is internal to sdk/ | +| При подключении реального SDK — меняем только `platform/mock.py` | Phase 05 touches `sdk/real.py` for workspace_path — acceptable, it's a refinement not a rewrite | +| Хотфиксы (< 20 строк) → Claude Code напрямую, не Codex | Phase 05 is >20 lines; must go through Codex via GSD | +| Реализацию делает codex:rescue | Plans must be PLAN.md format passable to Codex | +| Никогда не коммить `.env` | `.env.prod` must be in `.gitignore` — only `.env.prod.example` is committed | +| `uv sync` для зависимостей | No new pip installs; all deps already in pyproject.toml | +| pytest tests/ для тестов | Phase gate: `uv run pytest tests/ -q` must be green | + +--- + +## Sources + +### Primary (HIGH confidence) +- [VERIFIED: adapter/matrix/agent_registry.py] — current AgentDefinition/AgentRegistry structure +- [VERIFIED: adapter/matrix/bot.py] — _build_platform_from_env, MatrixBot, handle_invite, _materialize_incoming_attachments +- [VERIFIED: adapter/matrix/routed_platform.py] — _resolve_delegate logic +- [VERIFIED: adapter/matrix/files.py] — build_workspace_attachment_path, download_matrix_attachment +- [VERIFIED: adapter/matrix/handlers/agent.py] — !agent handler (to be deleted) +- [VERIFIED: adapter/matrix/handlers/auth.py] — provision_workspace_chat (to be replaced) +- [VERIFIED: adapter/matrix/handlers/context_commands.py] — !save/!load/!reset handlers +- [VERIFIED: adapter/matrix/handlers/__init__.py] — handler registration +- [VERIFIED: sdk/real.py] — RealPlatformClient, _build_chat_api, _attachment_from_send_file_event +- [VERIFIED: sdk/upstream_agent_api.py] — sys.path patching, AgentApi import +- [VERIFIED: external/platform-agent_api/lambda_agent_api/agent_api.py] — actual AgentApi implementation +- [VERIFIED: config/matrix-agents.yaml] — current format +- [VERIFIED: docker-compose.yml] — existing dev compose topology +- [VERIFIED: .env.example] — current env var set +- [VERIFIED: docs/deploy-architecture.md] — prod topology spec +- [VERIFIED: .planning/phases/05-mvp-deployment/05-CONTEXT.md] — locked decisions + +### Secondary (MEDIUM confidence) +- [ASSUMED: A1] lambda-agent image name — from CONTEXT.md D-08 description +- [ASSUMED: A2] Group room handling scope — inferred from D-05 wording + +--- + +## Metadata + +**Confidence breakdown:** +- Standard stack: HIGH — all libraries verified in existing code +- Architecture patterns: HIGH — all patterns verified against actual source files +- Pitfalls: HIGH — all pitfalls derived from reading actual code, not from training assumptions +- Test strategy: HIGH — test files enumerated and statuses verified by running pytest + +**Research date:** 2026-04-27 +**Valid until:** 2026-05-27 (stable codebase; short-circuit if platform-agent_api changes) From 0f07634955b1b999a95f9c6826b8d6ebb721be62 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Mon, 27 Apr 2026 23:00:33 +0300 Subject: [PATCH 27/55] docs(05): add validation strategy --- .../phases/05-mvp-deployment/05-VALIDATION.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 .planning/phases/05-mvp-deployment/05-VALIDATION.md diff --git a/.planning/phases/05-mvp-deployment/05-VALIDATION.md b/.planning/phases/05-mvp-deployment/05-VALIDATION.md new file mode 100644 index 0000000..abe4bcb --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-VALIDATION.md @@ -0,0 +1,84 @@ +--- +phase: 5 +slug: mvp-deployment +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-04-27 +--- + +# Phase 5 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | pytest | +| **Config file** | pyproject.toml | +| **Quick run command** | `pytest tests/adapter/matrix/ -v -x` | +| **Full suite command** | `pytest tests/ -v` | +| **Estimated runtime** | ~30 seconds | + +--- + +## Sampling Rate + +- **After every task commit:** Run `pytest tests/adapter/matrix/ -v -x` +- **After every plan wave:** Run `pytest tests/ -v` +- **Before `/gsd-verify-work`:** Full suite must be green +- **Max feedback latency:** 30 seconds + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------| +| 05-A-01 | A | 1 | D-02/D-03 | — | agent_id lookup by matrix_user_id only | unit | `pytest tests/adapter/matrix/test_agent_registry.py -v` | ❌ W0 | ⬜ pending | +| 05-A-02 | A | 1 | D-04 | — | per-agent URL used in delegates | unit | `pytest tests/adapter/matrix/test_routed_platform.py -v` | ❌ W0 | ⬜ pending | +| 05-B-01 | B | 1 | D-04/D-05 | — | welcome message sent on invite | unit | `pytest tests/adapter/matrix/test_onboarding.py -v` | ❌ W0 | ⬜ pending | +| 05-B-02 | B | 1 | D-10 | — | unauthorized user gets access-denied message | unit | `pytest tests/adapter/matrix/test_onboarding.py::test_unauthorized -v` | ❌ W0 | ⬜ pending | +| 05-B-03 | B | 1 | D-11 | — | !clear closes and reopens AgentApi | unit | `pytest tests/adapter/matrix/test_commands.py::test_clear -v` | ❌ W0 | ⬜ pending | +| 05-C-01 | C | 2 | D-05/D-06 | — | incoming file written to workspace_path/incoming/ | unit | `pytest tests/adapter/matrix/test_files.py -v` | ✅ | ⬜ pending | +| 05-C-02 | C | 2 | D-07 | — | outgoing MsgEventSendFile reads from workspace_path | unit | `pytest tests/adapter/matrix/test_files.py::test_outgoing_file -v` | ❌ W0 | ⬜ pending | +| 05-C-03 | C | 2 | D-08/D-09 | — | docker-compose.prod.yml has agents volume and both services | manual | see below | N/A | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `tests/adapter/matrix/test_agent_registry.py` — tests for user_agents lookup and per-agent base_url/workspace_path +- [ ] `tests/adapter/matrix/test_routed_platform.py` — updated tests for _resolve_delegate using user_agents +- [ ] `tests/adapter/matrix/test_onboarding.py` — tests for invite handling, welcome message, unauthorized user response +- [ ] `tests/adapter/matrix/test_commands.py` — tests for !clear command behavior +- [ ] Update `tests/adapter/matrix/test_files.py` — add outgoing file test + +*Existing: `tests/adapter/matrix/test_files.py` — already exists, covers incoming file path logic* + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| docker-compose.prod.yml full-stack launch | D-08/D-09 | Requires Docker daemon and lambda-agent:latest image | `docker compose -f docker-compose.prod.yml up` — verify both services start, volume mounts at /agents/ | +| Matrix bot invite + DM flow | D-04/D-05 | Requires live Matrix homeserver | Invite bot to DM, verify welcome message appears | + +--- + +## Validation Sign-Off + +- [ ] All tasks have `` verify or Wave 0 dependencies +- [ ] Sampling continuity: no 3 consecutive tasks without automated verify +- [ ] Wave 0 covers all MISSING references +- [ ] No watch-mode flags +- [ ] Feedback latency < 30s +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending From 26eb27b01ee25eff8bd6c0e0782b0d50fe2b52f8 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 00:42:24 +0300 Subject: [PATCH 28/55] docs(05): research mvp deployment phase --- .../phases/05-mvp-deployment/05-RESEARCH.md | 865 ++++++------------ 1 file changed, 303 insertions(+), 562 deletions(-) diff --git a/.planning/phases/05-mvp-deployment/05-RESEARCH.md b/.planning/phases/05-mvp-deployment/05-RESEARCH.md index 10ba8f8..6ccb0cd 100644 --- a/.planning/phases/05-mvp-deployment/05-RESEARCH.md +++ b/.planning/phases/05-mvp-deployment/05-RESEARCH.md @@ -1,670 +1,411 @@ -# Phase 05: MVP Deployment — Research +# Phase 05: MVP Deployment - Research -**Researched:** 2026-04-27 -**Domain:** Matrix bot deployment — config refactor, DM-first onboarding, file transfer, docker-compose prod topology -**Confidence:** HIGH (all findings verified against actual codebase) +**Researched:** 2026-04-28 +**Domain:** Matrix bot production deployment, restart reconciliation, per-room context isolation, shared-volume file transfer +**Confidence:** HIGH ---- +## Project Constraints (from CLAUDE.md) - -## User Constraints (from CONTEXT.md) - -### Locked Decisions - -**Single-chat architecture** -- D-01: chat_id=0 for all messages. One agent context per user. `!clear` resets context. -- D-02: Delete all multi-room infrastructure: C1/C2/C3, `!new`, `!archive`, `!rename`, Space-creation, room provisioning. Matrix bot operates only in DM room. -- D-03: Delete `!save` and `!load` — unreliable without persistent memory in agent. - -**Onboarding (DM-first)** -- D-04: On DM invite — accept, send welcome: "Привет! Я Lambda AI-агент. Просто напиши — и я отвечу. `!clear` чтобы начать новый разговор, `!context` чтобы посмотреть статус." -- D-05: No Space, no child rooms. All conversation in one DM room. - -**!clear (new command)** -- D-06: Reset agent context — close current AgentApi connection and create new (`await agent.close()` + `await agent.connect()`). Confirm: "Контекст сброшен. Начнём с чистого листа." -- D-11: No confirmation dialog — immediate reset. - -**!agent command** -- D-07: Delete completely. user→agent mapping is static from config. - -**Agent config (config/matrix-agents.yaml)** -- D-02 (config): Extend current matrix-agents.yaml — add user_agents dict and base_url/workspace_path fields per agent. -- D-03 (schema): AgentDefinition gains `base_url: str` and `workspace_path: str`. AgentRegistry adds `user_agents: dict[matrix_user_id, agent_id]` and `get_agent_id_by_user(matrix_user_id)`. - -**Routing user → agent in _build_platform_from_env** -- D-04 (routing): Per-agent URL from config instead of global AGENT_BASE_URL. `_build_platform_from_env` builds delegates with correct base_url per agent. `RoutedPlatformClient._resolve_delegate` uses user_agents from registry. - -**Incoming files (user → agent)** -- D-05 (files): Path inside agent workspace: `incoming/{filename}`. Absolute: `{workspace_path}/incoming/{filename}`. Update `files.py`: `build_workspace_attachment_path` takes agent workspace_path and builds `incoming/{filename}`. Pass to `agent.send_message()` as `attachments=["incoming/{filename}"]` (relative to /workspace). -- D-06 (files): workspace_path is taken from AgentDefinition by user's agent_id. - -**Outgoing files (agent → user)** -- D-07 (files): On `MsgEventSendFile(path="output/report.pdf")` — read from `{workspace_path}/{path}`. Send as Matrix file message. - -**docker-compose for prod** -- D-08: `docker-compose.prod.yml` includes: Matrix bot + agent container (placeholder image `lambda-agent:latest`) + named volume `agents`. -- D-09: Named volume `agents` mounted in Matrix bot as `/agents/` and in agent container as `/workspace`. Env vars from `.env.prod`. Start: `docker compose -f docker-compose.prod.yml up`. - -**Unauthorized users** -- D-10: If Matrix user_id not in `user_agents` — accept invite, reply: "К вашему аккаунту не привязан агент. Напишите @og_mput в Telegram для получения доступа." Ignore further messages (or repeat message). - -**!settings and other settings commands** -- D-12: Delete `!settings`, `!settings soul`, `!settings skills`, `!settings safety`. - -### Claude's Discretion -- MATRIX_AGENT_REGISTRY_PATH — keep as env var for config path (already exists) -- Format of .env.prod -- Group room invites (non-DM) — reject automatically -- Existing Space+rooms for old users — ignore, do not migrate - -### Deferred Ideas (OUT OF SCOPE) -- platform-master integration (dynamic `get_agent_url` via POST /api/v1/create) — when feat/storage is ready -- !agent as admin-override — not needed for MVP -- Per-chat context isolation via different chat_id (currently chat_id=0) — waiting for platform signal - - ---- +- All platform calls must stay behind `platform/interface.py` (`PlatformClient` protocol). +- Current platform implementation is a mock / replaceable adapter; architecture must not depend on unfinished upstream SDK. +- Keep architecture decisions inside this repo and document contracts locally. +- Prefer async, adapter/core separation, and do not bypass the existing `core/` and `adapter/` layering. +- Use `uv sync` for dependency installation. +- Use `pytest tests/ -v` and adapter-specific pytest slices for verification. +- Never commit `.env`. +- Dependency order remains fixed: `core/` first, `platform/` second, adapters after that. ## Summary -Phase 05 is a code-and-config refactor of the existing Matrix adapter. There is no new framework to learn — the full stack (matrix-nio, AgentApi, docker-compose) is already in use. The work is: (1) simplify the data model from multi-room to single DM room per user, (2) extend AgentRegistry with per-user routing and per-agent URLs/paths, (3) reroute file I/O to the shared `/agents/` volume, (4) write a prod docker-compose, and (5) delete substantial legacy code (Space provisioning, C1/C2/C3, !agent, !save, !load, !settings). +Phase 05 should not introduce a new stack. The established implementation path is to harden the existing `matrix-nio + SQLiteStore + RoutedPlatformClient + shared workspace volume` design so production restart behavior matches the current Space+rooms UX. The main architectural rule is: Matrix topology is authoritative for room existence, while local SQLite metadata is authoritative only after reconciliation has rebuilt it. -The current codebase has 35 failing tests (pre-existing on `feat/deploy`), mostly in `test_dispatcher.py`, `test_invite_space.py`, `test_routed_platform.py` — all testing behaviors that Phase 05 will delete or replace. New tests must cover the simplified DM-first invite flow, the user_agents lookup path, and the new file path logic. Existing passing tests (203) must stay green. +The production-safe approach is to bind every working Matrix room to its own durable `platform_chat_id`, rotate only that identifier for `!clear`, and make restart recovery idempotent. Reconciliation should rebuild `user_meta`, `room_meta`, `ChatManager` entries, and missing routing fields from Matrix Space membership and room state before `sync_forever()` begins processing live traffic. Unknown rooms must be reconciled first, not silently converted into new chats. -**Primary recommendation:** Execute as three sequential mini-plans: (A) config/registry extension + routing, (B) DM-first onboarding + !clear + legacy deletion, (C) file transfer + docker-compose.prod.yml + .env.prod. +For files, keep the current shared-volume contract and relative `workspace_path` transport. Do not build HTTP file shims or embed file payloads in bot-side state. For deployment artifacts, split runtime intent explicitly: `docker-compose.prod.yml` is a bot-only handoff contract, while `docker-compose.fullstack.yml` is the internal E2E harness that brings up platform services and shared volumes together. ---- +**Primary recommendation:** Implement Phase 05 as a reconciliation-and-deploy hardening pass on the current Matrix stack, with Matrix Space state as source of truth and per-room `platform_chat_id` as the routing key. ## Standard Stack -All libraries are already installed and in use. No new dependencies. +### Core +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| `matrix-nio` | 0.25.2 | Async Matrix client, Spaces, media upload/download, token login, sync loop | Already in repo; official docs confirm support for Spaces, token login, `room_put_state`, `upload`, `download`, and `sync_forever` | +| `sqlite3` / `SQLiteStore` | stdlib / repo-local | Durable bot metadata (`room_meta`, `user_meta`, routing state) | Small, local, restart-safe KV layer already used by runtime and tests | +| `PyYAML` | 6.0.3 | Agent registry / deployment config parsing | Current repo standard for `config/matrix-agents.yaml`-style artifacts | +| `httpx` | 0.28.1 | Async HTTP for auxiliary platform calls | Already used; fits async runtime and current codebase | +| Docker Compose | v2 spec; local install `v2.40.3` | Prod/fullstack topology, shared named volumes, health-gated startup | Officially supports multi-file overlays, named volumes, and `service_healthy` gating | -### Core (already in pyproject.toml) +### Supporting +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| `structlog` | 25.5.0 | Structured runtime logging | Use for reconciliation summaries, routing mismatches, and deploy diagnostics | +| `pydantic` | 2.13.3 | Typed config / payload validation | Use for any new deployment config or reconciliation report structures | +| `python-dotenv` | 1.2.2 | Local env loading | Keep for local and compose-driven runtime config | +| `pytest` | 9.0.3 | Test runner | Full phase verification and regression slices | +| `pytest-asyncio` | 1.3.0 | Async test execution | Required for reconciliation/runtime tests | -| Library | Version | Purpose | Source | -|---------|---------|---------|--------| -| matrix-nio | installed | Matrix client — join rooms, send messages, upload files | [VERIFIED: adapter/matrix/bot.py imports] | -| pyyaml | installed | YAML config parsing in AgentRegistry | [VERIFIED: agent_registry.py line 7] | -| aiohttp | installed | WebSocket transport inside AgentApi | [VERIFIED: external/platform-agent_api/lambda_agent_api/agent_api.py] | -| structlog | installed | Structured logging | [VERIFIED: bot.py imports] | -| python-dotenv | installed | .env loading | [VERIFIED: bot.py line 79] | +### Alternatives Considered +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| `matrix-nio` | Synapse Admin / raw Matrix HTTP calls | Worse fit; repo already depends on nio abstractions and tests | +| repo-local `SQLiteStore` | Redis/Postgres | Unnecessary operational scope increase for MVP deployment | +| shared volume file flow | custom file proxy / presigned URLs | More moving parts, more auth/cleanup edge cases, no need for MVP | +| split compose files | one overloaded compose file with profiles | Harder operator handoff; less explicit prod vs internal-test intent | -### AgentApi (external, local path) - -`external/platform-agent_api/lambda_agent_api/agent_api.py` — imported via `sdk/upstream_agent_api.py` which patches `sys.path`. - -**Verified constructor signature** [VERIFIED: agent_api.py]: -```python -AgentApi( - agent_id: str, - base_url: str, # ws://host:port/agent_N/ - callback: Optional[Callable] = None, - on_disconnect: Optional[Callable[["AgentApi"], None]] = None, - chat_id: int = 0, -) +**Installation:** +```bash +uv sync ``` -**Key AgentApi facts** [VERIFIED: agent_api.py]: -- `self.url = urljoin(base_url, f"v1/agent_ws/{chat_id}/")` — builds WebSocket URL automatically from base_url + chat_id -- `await agent.connect()` — must be called before `send_message()` -- `await agent.close()` — explicit close; triggers `on_disconnect` callback, drains queue -- `async for event in agent.send_message(text, attachments=["incoming/file.pdf"])` — attachments are paths relative to `/workspace` -- `agent.id` attribute (not `agent_id`) — used as dict key in connection pool +**Version verification:** Verified on 2026-04-28 from PyPI and local environment. -**Lifecycle for !clear** [VERIFIED: agent_api.py `close()` + `connect()`]: -Close → triggers `on_disconnect` → removes from pool → next message recreates. Or: for an immediately-reset flow, call `close()` then `connect()` on the same instance (safe — `_connected` flag is reset in `_cleanup()`). - ---- +| Package | Verified Version | Publish Date | Source | +|---------|------------------|--------------|--------| +| `matrix-nio` | 0.25.2 | 2024-10-04 | PyPI | +| `httpx` | 0.28.1 | 2024-12-06 | PyPI | +| `structlog` | 25.5.0 | 2025-10-27 | PyPI | +| `pydantic` | 2.13.3 | 2026-04-20 | PyPI | +| `aiohttp` | 3.13.5 | 2026-03-31 | PyPI | +| `PyYAML` | 6.0.3 | 2025-09-25 | PyPI | +| `python-dotenv` | 1.2.2 | 2026-03-01 | PyPI | +| `pytest` | 9.0.3 | 2026-04-07 | PyPI | +| `pytest-asyncio` | 1.3.0 | 2025-11-10 | PyPI | ## Architecture Patterns -### Existing Code to Modify (not rewrite) - -``` +### Recommended Project Structure +```text adapter/matrix/ - agent_registry.py — extend AgentDefinition + AgentRegistry - bot.py — _build_platform_from_env, handle_invite, _materialize_incoming_attachments - routed_platform.py — _resolve_delegate (add user_agents lookup) - files.py — build_workspace_attachment_path (new path logic) - room_router.py — resolve_chat_id (chat_id=0 for DM-first, no C1/C2/C3 lookup needed) - handlers/ - agent.py — DELETE or make no-op - auth.py — replace provision_workspace_chat with simple DM-accept - context_commands.py — DELETE make_handle_save, make_handle_load; keep make_handle_context - settings.py — DELETE or strip handle_settings, handle_settings_soul, etc. - __init__.py — unregister deleted commands +├── bot.py # startup, sync bootstrap, live callbacks +├── reconciliation.py # new: restart recovery from Matrix state +├── files.py # shared-volume path building / materialization +├── routed_platform.py # room -> agent_id + platform_chat_id routing +├── store.py # room_meta/user_meta helpers and counters +└── handlers/ + ├── auth.py # Space + first room provisioning + ├── chat.py # !new / !archive / !rename + └── context_commands.py # !save / !load / !clear / !context -config/ - matrix-agents.yaml — extend format - -docker-compose.prod.yml — new file -.env.prod — new file (or .env.example update) +deploy/ +├── docker-compose.prod.yml # bot-only handoff +└── docker-compose.fullstack.yml # internal E2E stack ``` -### Pattern 1: AgentRegistry Extension - -Current `AgentDefinition` has only `agent_id` and `label`. New fields needed [VERIFIED: CONTEXT.md D-03]: - +### Pattern 1: Matrix Space State Is Canonical, SQLite Is Rebuildable +**What:** Treat Matrix Space membership and child-room state as the source of truth for room topology; use local SQLite metadata as a cached routing index that reconciliation can rebuild. +**When to use:** Startup, DB loss, stale local metadata, and any deployment where rooms may outlive the bot process. +**Example:** ```python -# adapter/matrix/agent_registry.py - -@dataclass(frozen=True) -class AgentDefinition: - agent_id: str - label: str - base_url: str # ws://lambda.coredump.ru:7000/agent_0/ - workspace_path: str # /agents/0/ - - -class AgentRegistry: - def __init__( - self, - agents: list[AgentDefinition], - user_agents: dict[str, str], # Matrix user_id -> agent_id - ) -> None: - self.agents = tuple(agents) - self._by_id = {agent.agent_id: agent for agent in self.agents} - self.user_agents = user_agents # NEW - - def get_agent_id_by_user(self, matrix_user_id: str) -> str | None: # NEW - return self.user_agents.get(matrix_user_id) +# Source: repo pattern from adapter/matrix/store.py + Matrix Space state +room_meta = { + "room_type": "chat", + "chat_id": "C7", + "display_name": "Research", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + "agent_id": "agent-1", + "platform_chat_id": "42", +} +await set_room_meta(store, room_id, room_meta) +await chat_mgr.get_or_create( + user_id=room_meta["matrix_user_id"], + chat_id=room_meta["chat_id"], + platform="matrix", + surface_ref=room_id, + name=room_meta["display_name"], +) ``` -### Pattern 2: _build_platform_from_env with Per-Agent URLs - -Current code uses `_agent_base_url_from_env()` globally for all delegates [VERIFIED: bot.py lines 148-161]. New pattern: - +### Pattern 2: Per-Room `platform_chat_id` Is the Only Real Context Boundary +**What:** Route every working Matrix room to its own durable `platform_chat_id`. +**When to use:** Normal messaging, `!save`, `!load`, `!context`, `!clear`, restart restoration. +**Example:** ```python -def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> PlatformClient: - backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower() - if backend == "real": - prototype_state = PrototypeStateStore() - registry = _load_agent_registry_from_env(required=True) - assert registry is not None - delegates = { - agent.agent_id: RealPlatformClient( - agent_id=agent.agent_id, - agent_base_url=agent.base_url, # PER-AGENT URL from config - prototype_state=prototype_state, - platform="matrix", - ) - for agent in registry.agents - } - return RoutedPlatformClient( - chat_mgr=chat_mgr, - store=store, - delegates=delegates, - registry=registry, # pass registry for user_agents lookup - ) - return MockPlatformClient() +# Source: adapter/matrix/routed_platform.py + adapter/matrix/handlers/context_commands.py +old_chat_id = room_meta["platform_chat_id"] +new_chat_id = await next_platform_chat_id(store) +await set_platform_chat_id(store, room_id, new_chat_id) + +disconnect = getattr(platform, "disconnect_chat", None) +if callable(disconnect): + await disconnect(old_chat_id) ``` -### Pattern 3: RoutedPlatformClient._resolve_delegate (user_agents lookup) - -Current implementation [VERIFIED: routed_platform.py lines 80-110] resolves agent via `room_meta.get("agent_id")` — requires the room to be pre-bound to an agent. New DM-first model: look up agent_id from `user_agents` dict by Matrix user_id. - -The `_resolve_delegate` signature receives `user_id` (Matrix user_id string) and `local_chat_id` (room_id in DM-first model). New logic: - +### Pattern 3: `!clear` Means Chat-ID Rotation, Not Global Wipe +**What:** Implement real clear by rotating only the current room's `platform_chat_id` and disconnecting the old upstream chat session. +**When to use:** User-triggered context reset for one room. +**Example:** ```python -async def _resolve_delegate( - self, user_id: str, local_chat_id: str -) -> tuple[PlatformClient, str]: - # 1. Look up agent_id by Matrix user_id - agent_id = self._registry.get_agent_id_by_user(user_id) - if agent_id is None: - raise PlatformError( - f"no agent configured for user: {user_id}", - code="MATRIX_USER_NOT_CONFIGURED", - ) - # 2. Get delegate - delegate = self._delegates.get(agent_id) - if delegate is None: - raise PlatformError(f"unknown agent: {agent_id}", code="MATRIX_AGENT_NOT_FOUND") - # 3. chat_id=0 always (single-chat arch, D-01) - return delegate, "0" +# Source: adapter/matrix/handlers/context_commands.py +room_id = await _resolve_room_id(event, chat_mgr) +old_chat_id = (room_meta or {}).get("platform_chat_id") or room_id +new_chat_id = await next_platform_chat_id(store) +await set_platform_chat_id(store, room_id, new_chat_id) ``` -### Pattern 4: DM-First Invite Handler - -Replace `handle_invite` + `provision_workspace_chat` in `auth.py` [VERIFIED: auth.py lines 122-163]: - +### Pattern 4: Shared-Volume File Handoff Uses Relative Workspace Paths +**What:** Persist incoming Matrix media into a room-scoped path under the shared workspace, and pass only relative paths to the agent. +**When to use:** User uploads, staged attachments, agent-emitted files. +**Example:** ```python -async def handle_invite(client, room, event, platform, store, auth_mgr, chat_mgr) -> None: - matrix_user_id = getattr(event, "sender", "") - # Reject group rooms (non-DM) — Claude's discretion - is_dm = getattr(room, "is_direct", True) # matrix-nio: RoomCreateEvent m.room.create has is_direct - if not is_dm: - await client.room_leave(room.room_id) - return - - await client.join(room.room_id) - - # Check authorization - if not _is_authorized(matrix_user_id, registry): # uses user_agents lookup - await client.room_send(room.room_id, "m.room.message", { - "msgtype": "m.text", - "body": "К вашему аккаунту не привязан агент. Напишите @og_mput в Telegram для получения доступа." - }) - return - - # Idempotent: don't send welcome twice - meta = await get_room_meta(store, room.room_id) - if meta and meta.get("welcomed"): - return - - await set_room_meta(store, room.room_id, { - "matrix_user_id": matrix_user_id, - "chat_id": "0", # single-chat: chat_id=0 always - "welcomed": True, - }) - await client.room_send(room.room_id, "m.room.message", { - "msgtype": "m.text", - "body": "Привет! Я Lambda AI-агент. Просто напиши — и я отвечу. !clear чтобы начать новый разговор, !context чтобы посмотреть статус." - }) +# Source: adapter/matrix/files.py +relative_path = ( + Path("surfaces") / "matrix" / safe_user / safe_room / "inbox" / f"{stamp}-{safe_name}" +) +return Attachment( + type=attachment.type, + url=attachment.url, + filename=filename, + mime_type=attachment.mime_type, + workspace_path=relative_path.as_posix(), +) ``` -**Note on is_direct detection:** matrix-nio's `InviteMemberEvent` does not expose `is_direct` directly. The `MatrixRoom` object has `room_type` — DM rooms created by the client have `join_rule = "invite"` and member count 2. A safer approach: accept all invites, check `user_agents` for authorization. Group room detection is a Claude's Discretion item — the simplest implementation is to not detect it at phase 05 and only reject unauthorized users. - -### Pattern 5: File Path for Incoming Attachments - -Current `build_workspace_attachment_path` [VERIFIED: files.py lines 31-46] builds: -`surfaces/matrix/{safe_user}/{safe_room}/inbox/{stamp}-{filename}` - -New path needed [VERIFIED: CONTEXT.md D-05]: -`incoming/{filename}` (relative), absolute: `{workspace_path}/incoming/{filename}` - -New signature: -```python -def build_workspace_attachment_path( - *, - workspace_path: str, # agent's workspace_path from AgentDefinition, e.g. "/agents/0/" - filename: str, - timestamp: str | None = None, -) -> tuple[str, Path]: - """Returns (relative_path_for_agent, absolute_path_for_download).""" - stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S") - safe_name = _sanitize_component(filename) or "attachment.bin" - relative_path = f"incoming/{stamp}-{safe_name}" # relative to /workspace - absolute_path = Path(workspace_path) / relative_path - return relative_path, absolute_path -``` - -**Callers:** `download_matrix_attachment()` in files.py and `_materialize_incoming_attachments()` in bot.py. Both need to receive `workspace_path` (from `AgentDefinition`). The bot must resolve `agent_id` for the sender before downloading — requires `registry.get_agent_id_by_user(matrix_user_id)`. - -### Pattern 6: Outgoing Files (MsgEventSendFile handling) - -Current `send_message` in `sdk/real.py` [VERIFIED: real.py lines 88-98] already calls `_attachment_from_send_file_event` but the result goes into `MessageResponse.attachments` — which `OutgoingMessage.attachments` then carries. The `send_outgoing()` in bot.py [VERIFIED: bot.py lines 656-686] already handles `event.attachments` by resolving `attachment.workspace_path` via `resolve_workspace_attachment_path(workspace_root, ...)`. - -**Current problem:** `workspace_root` is `Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace"))` — a global, not per-agent. With shared volume `/agents/`, the agent workspace is `/agents/0/`, `/agents/1/`, etc. - -**Fix strategy:** When processing `MsgEventSendFile(path="output/report.pdf")` for agent N, the absolute path is `/agents/N/output/report.pdf`. The `workspace_path` stored in `Attachment` (from `_attachment_from_send_file_event`) is `"output/report.pdf"`. The `workspace_root` passed to `resolve_workspace_attachment_path` must be the agent's `workspace_path` (e.g. `/agents/0/`). - -**Two options:** -1. Store absolute path directly in `Attachment.workspace_path` (simplest — no env var needed) -2. Pass per-agent workspace_root through context - -Option 1 is simpler: in `_attachment_from_send_file_event`, when building `Attachment`, set `workspace_path` to the absolute path (`{agent_workspace_path}/output/report.pdf`). The `resolve_workspace_attachment_path` function already handles absolute paths [VERIFIED: files.py line 87-90: `if path.is_absolute(): return path`]. - -This means `RealPlatformClient` needs to know the agent's `workspace_path` — pass it in constructor. - -### Pattern 7: !clear Command - -New handler in `context_commands.py` (or new `clear.py`): - -```python -def make_handle_clear(agent_pool: dict[str, AgentApi]): - async def handle_clear(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr): - # The "platform" here is RoutedPlatformClient. - # Need to access the underlying RealPlatformClient and its AgentApi. - # Two approaches: - # A) Give RoutedPlatformClient a reset_agent(user_id) method - # B) Access delegate directly via platform._delegates[agent_id] - agent_id = platform._registry.get_agent_id_by_user(event.user_id) - if agent_id and agent_id in platform._delegates: - delegate = platform._delegates[agent_id] - await delegate.reset_agent() # new method on RealPlatformClient - return [OutgoingMessage(chat_id=event.chat_id, text="Контекст сброшен.")] - return handle_clear -``` - -**reset_agent() on RealPlatformClient:** Close the active AgentApi connection. Since `RealPlatformClient` currently creates a fresh `AgentApi` per request (see `_build_chat_api` — no connection pool) [VERIFIED: real.py lines 173-178], there's nothing to close. The reset is implicit — the next `send_message` creates a fresh `AgentApi(chat_id="0")` which reconnects. - -**However:** `chat_id="0"` is a string in `RealPlatformClient._build_chat_api` [VERIFIED: real.py line 177: `chat_id=str(chat_id)`], but `AgentApi` constructor takes `chat_id: int = 0`. The `urljoin(base_url, f"v1/agent_ws/{chat_id}/")` call will produce `v1/agent_ws/0/` regardless. - -**Actual reset mechanism with current RealPlatformClient:** Since a new AgentApi is created per `send_message()` call (stateless client pattern), the "context" is held in the remote agent's `MemorySaver`. True reset = reconnect at the agent side. The `!reset` command already does `disconnect_chat` [VERIFIED: context_commands.py `make_handle_reset`]. The `!clear` can reuse this pattern: call `platform.disconnect_chat("0")` if available, or simply confirm immediately (MemorySaver resets on next connection with a fresh `chat_id` key — but chat_id=0 is always 0, so MemorySaver persists across connections). - -**Implication:** True context reset with MemorySaver requires the agent to restart or use a different chat_id. For Phase 05 MVP, `!clear` can: (a) confirm to user "Контекст сброшен." and (b) note this is best-effort until agent side supports it. This matches D-11 (immediate, no confirmation dialog). - -### Pattern 8: docker-compose.prod.yml - +### Pattern 5: Compose Split By Operational Intent +**What:** Keep one compose artifact for operator handoff and one for internal full-stack testing. +**When to use:** Deployment packaging. +**Example:** ```yaml +# docker-compose.prod.yml services: matrix-bot: image: surfaces-bot:latest - build: . - env_file: .env.prod + env_file: .env volumes: - - agents:/agents/ - - ./config:/app/config:ro - restart: unless-stopped - - agent-0: - image: lambda-agent:latest - env_file: .env.prod - environment: - AGENT_ID: "agent-0" - volumes: - - agents:/workspace - restart: unless-stopped + - agents:/agents +# docker-compose.fullstack.yml +services: + matrix-bot: + extends: + file: docker-compose.prod.yml + service: matrix-bot + platform-agent: + ... volumes: agents: - driver: local ``` -**Note:** `lambda-agent:latest` is a placeholder image name per D-08. The platform team owns the actual image. - ### Anti-Patterns to Avoid - -- **Do not create per-request AgentApi instances in a long-running pool** — the current `RealPlatformClient` already does this correctly (stateless per request). Don't change this pattern for Phase 05. -- **Do not add chat_id logic** — single-chat arch means chat_id=0 always. Any code that increments or stores platform_chat_ids in room_meta is legacy being deleted. -- **Do not try to detect is_direct at invite time via matrix-nio** — the library's InviteMemberEvent doesn't expose this reliably. Accept all invites, authorize by user_agents lookup. -- **Do not change sdk/real.py AgentApi constructor call** — `_build_chat_api` uses `chat_id=str(chat_id)`. Keep as is; the AgentApi accepts string-coercible chat_id. - ---- +- **Lazy bootstrap as restart strategy:** `_bootstrap_unregistered_room()` is acceptable for first-contact repair, not as the primary restart recovery path in production. +- **Per-user context identity:** a user-level or DM-level chat id breaks Space+rooms isolation and makes `!clear` incorrect. +- **Global reset endpoint semantics:** `!clear` must not wipe other rooms or all agent state for a user. +- **Absolute attachment paths in platform payloads:** keep agent attachment references relative to its workspace contract. +- **Sleep-based service readiness:** use Compose healthchecks and dependency conditions, not shell `sleep`. ## Don't Hand-Roll | Problem | Don't Build | Use Instead | Why | |---------|-------------|-------------|-----| -| File upload to Matrix | Custom HTTP multipart | `client.upload(handle, content_type, filename, filesize)` | matrix-nio provides this; already used in bot.py send_outgoing | -| Matrix file message | Custom m.room.message | `client.room_send(room_id, "m.room.message", {"msgtype": "m.file", ...})` | Already implemented in send_outgoing | -| YAML parsing | Custom parser | `yaml.safe_load()` (already in agent_registry.py) | Already works; just extend the schema | -| WebSocket to agent | Custom aiohttp ws | `AgentApi` from external/platform-agent_api | Already used via sdk/real.py | +| Matrix room/Space protocol | Raw custom HTTP wrappers for state events | `matrix-nio` `room_create`, `room_put_state`, `space_get_hierarchy`, `sync_forever`, `upload`, `download` | Official support already exists and repo tests are built around nio | +| Restart topology discovery | Ad hoc timeline scraping | Full-state sync plus room state / Space child reconciliation | Timeline replay is noisy and brittle; state is the stable source | +| File transfer bus | Base64 blobs or custom bot-side file API | Shared `/agents/` volume with relative `workspace_path` | Lower operational complexity and already matches upstream agent contract | +| Compose startup sequencing | Shell loops / sleeps | `healthcheck` + `depends_on: condition: service_healthy` | Official Compose behavior is deterministic and observable | +| Context reset | Deleting all SQLite rows or resetting the whole user | Rotate current room `platform_chat_id` and drop that room's live agent connection | Preserves other rooms and matches user expectation | ---- +**Key insight:** The deceptively hard problems in this phase are already solved by the current stack: Matrix room state, nio media handling, named volumes, and service health gating. Custom alternatives add more failure modes than value. ## Common Pitfalls -### Pitfall 1: `_materialize_incoming_attachments` uses global SURFACES_WORKSPACE_DIR +### Pitfall 1: Unknown room after restart creates a duplicate working chat +**What goes wrong:** The bot treats an existing room as unregistered and provisions a fresh room/tree. +**Why it happens:** Local SQLite metadata is missing, but Matrix topology still exists. +**How to avoid:** Run reconciliation before live sync callbacks; only allow lazy bootstrap for genuinely new first-contact rooms. +**Warning signs:** New `Чат N` rooms appear after restart without a matching user action. -**What goes wrong:** Bot downloads file to `/workspace/surfaces/matrix/...` (old path) when it should write to `/agents/0/incoming/...`. -**Why it happens:** `_materialize_incoming_attachments` in bot.py [VERIFIED: bot.py line 449] reads `SURFACES_WORKSPACE_DIR` env var. In prod, this needs to be `/agents/` — but the per-user path varies. -**How to avoid:** Pass the agent's `workspace_path` (from `AgentDefinition`) into `download_matrix_attachment`. The bot must resolve `matrix_user_id → agent_id → AgentDefinition.workspace_path` before calling download. The `registry` object is available in `build_runtime()` but not currently threaded into `MatrixBot._materialize_incoming_attachments`. Either (a) store registry on `MatrixRuntime`, or (b) pass it into `MatrixBot.__init__`. +### Pitfall 2: `!clear` resets the wrong scope +**What goes wrong:** Clearing one room also clears another room, or does nothing because the upstream session key did not change. +**Why it happens:** Context is keyed by user or local `chat_id` instead of durable room-local `platform_chat_id`. +**How to avoid:** Always resolve room -> `platform_chat_id`, rotate it, and disconnect only the old upstream chat. +**Warning signs:** Two rooms share response history or `!context` reports the same platform context id. -### Pitfall 2: AgentRegistry reference not available in handlers +### Pitfall 3: Space child linkage is incomplete +**What goes wrong:** Rooms exist but do not appear correctly under the user's Space. +**Why it happens:** Missing or malformed `m.space.child` state, especially missing `via` data. +**How to avoid:** Persist `space_id`, write `m.space.child` with `state_key=room_id`, and reconcile child links on startup. +**Warning signs:** Element shows the room outside the Space, or not at all in the hierarchy. -**What goes wrong:** `handle_invite`, `_check_agent_routing`, `_materialize_incoming_attachments` all need the registry to look up user_agents. Currently registry is loaded in `build_runtime()` and passed only to `register_matrix_handlers`. -**Why it happens:** `MatrixBot` doesn't store the registry. Only the dispatcher gets it. -**How to avoid:** Store `registry: AgentRegistry | None` on `MatrixRuntime`. Thread it into `MatrixBot`. +### Pitfall 4: Shared volume works locally but fails in deployment +**What goes wrong:** Agent-generated files cannot be read by the bot, or bot-downloaded files are unreadable by the agent. +**Why it happens:** Mount mismatch, wrong root (`/workspace` vs `/agents`), or container user/group permissions. +**How to avoid:** Standardize one shared root, keep relative workspace paths, and align container permissions with Compose volume configuration. +**Warning signs:** Attachment paths exist in metadata but not on disk inside the other container. -### Pitfall 3: Existing tests test behaviors being deleted - -**What goes wrong:** 35 currently failing tests (pre-existing) test Space provisioning, !agent, C1/C2/C3, !save/!load. After deletion, these tests must be deleted or replaced. -**Why it happens:** The test suite was written for the old multi-room architecture. -**How to avoid:** Plan explicitly identifies which test files to delete/rewrite: -- Delete: `test_invite_space.py`, `test_agent_handler.py`, `test_chat_space.py` -- Rewrite: `test_dispatcher.py` (large — slim to DM-first behavior), `test_routed_platform.py` (update to user_agents lookup) -- Update: `test_files.py` (new path format) -- Keep: `test_converter.py`, `test_store.py`, `test_restart_persistence.py`, `test_routing_enforcement.py`, `test_context_commands.py` (partial) - -### Pitfall 4: `resolve_chat_id` returns C1/C2/C3 chat IDs - -**What goes wrong:** `room_router.resolve_chat_id` [VERIFIED: room_router.py] reads `room_meta.get("chat_id")`. Old room_meta stores `"C1"`, `"C2"` etc. In DM-first model, chat_id is always `"0"`. -**How to avoid:** Update `set_room_meta` calls in the new invite handler to set `"chat_id": "0"`. The `resolve_chat_id` function can remain as-is — it will return `"0"` when that's what's stored. - -### Pitfall 5: `RoutedPlatformClient._resolve_delegate` expects room_meta with agent_id - -**What goes wrong:** Current `_resolve_delegate` [VERIFIED: routed_platform.py lines 80-110] reads `room_meta.get("agent_id")` — requires the room to have been pre-bound. In DM-first model with user_agents lookup, rooms are never explicitly bound. -**How to avoid:** Replace the agent_id lookup with `registry.get_agent_id_by_user(user_id)`. The `user_id` parameter is the Matrix user_id string, which is already passed into `send_message()` / `stream_message()`. - -### Pitfall 6: `RealPlatformClient` needs workspace_path for outgoing file resolution - -**What goes wrong:** When agent emits `MsgEventSendFile(path="output/report.pdf")`, the current `_attachment_from_send_file_event` strips `/workspace/` prefix [VERIFIED: real.py lines 207-218] leaving `"output/report.pdf"`. Then `send_outgoing` in bot.py resolves it with `SURFACES_WORKSPACE_DIR` — which doesn't know which agent's workspace to use. -**How to avoid:** Add `workspace_path: str` to `RealPlatformClient.__init__`. In `_attachment_from_send_file_event`, build absolute path: `Path(workspace_path) / event.path`. Store absolute path in `Attachment.workspace_path`. `resolve_workspace_attachment_path` already returns absolute paths unchanged [VERIFIED: files.py line 87-90]. - -### Pitfall 7: docker-compose.prod.yml volume mount collision - -**What goes wrong:** If `/agents/` named volume is used and the agent container also mounts it as `/workspace`, all agents share the same volume root. Agent-0 writes to `/workspace/output/`, Agent-1 also writes to `/workspace/output/` — collision. -**Why it happens:** Named volume `agents` is mounted as `/workspace` in ALL agent containers. -**How to avoid:** Each agent container gets its own volume or subpath. With Docker Compose named volumes, subpath mounts are possible in Compose v2.17+ with `volume.subpath`. Or: use separate named volumes per agent (`agents_0`, `agents_1`). Or: the agent container is configured with `WORKSPACE_SUBDIR` and uses `/workspace/{agent_id}/`. Per D-08, there is one placeholder agent container — this is a platform concern. For Phase 05 with a single placeholder, use the simplest approach: one `agents` volume, agent-0 mounted at `/workspace`, bot at `/agents/`, with `workspace_path: "/agents/0/"` in config — the bot writes to `/agents/0/incoming/` which the agent reads from `/workspace/0/incoming/`. **Wait — this is a mismatch.** - -**Correct topology per deploy-architecture.md** [VERIFIED: docs/deploy-architecture.md]: -- Volume `agents` mounted in bot as `/agents/` -- Volume `agents` mounted in agent-0 as `/workspace` -- Agent workspace_path in config: `/agents/0/` -- Bot writes file to `/agents/0/incoming/photo.jpg` -- Agent reads from `/workspace/0/incoming/photo.jpg` — WORKS if agent container mounts the volume at `/workspace` and the volume root contains `/0/` subdirectory. - -So: one named volume, mounted identically in both containers (at `/agents/` in bot, at `/workspace` in agent). The subdirectory `/0/` is the isolation boundary. **This requires the agent container to be aware it lives in `/workspace/0/` not `/workspace/`.** This is a platform concern. For Phase 05 single-agent placeholder, this still works because there's only one agent. - ---- +### Pitfall 5: Compose `depends_on` starts too early +**What goes wrong:** Bot starts before dependent services are actually ready. +**Why it happens:** Short-form `depends_on` only waits for container start, not health. +**How to avoid:** Use healthchecks and long-form `depends_on` with `service_healthy` in the full-stack compose file. +**Warning signs:** First requests fail after fresh `docker compose up`, then succeed on retry. ## Code Examples -### AgentApi usage (verified from source) +Verified patterns from official sources and current repo: +### Create a Space with `matrix-nio` ```python -# Source: external/platform-agent_api/lambda_agent_api/agent_api.py - -agent = AgentApi( - agent_id="agent-0", - base_url="ws://lambda.coredump.ru:7000/agent_0/", - on_disconnect=lambda a: connected_agents.pop(a.id, None), - chat_id=0, +# Source: matrix-nio API docs +space_resp = await client.room_create( + name=f"Lambda — {display_name}", + visibility=RoomVisibility.private, + invite=[matrix_user_id], + space=True, ) -await agent.connect() # Must call before send_message - -async for event in agent.send_message("Hello", attachments=["incoming/photo.jpg"]): - if isinstance(event, MsgEventTextChunk): - print(event.text) - elif isinstance(event, MsgEventSendFile): - # event.path = "output/report.pdf" - abs_path = Path(agent_workspace_path) / event.path - -await agent.close() # Triggers on_disconnect ``` -### Matrix file upload (verified from bot.py) - +### Add a child room to a Space ```python -# Source: adapter/matrix/bot.py send_outgoing() - -with file_path.open("rb") as handle: - upload_response, _ = await client.upload( - handle, - content_type=attachment.mime_type or "application/octet-stream", - filename=attachment.filename or file_path.name, - filesize=file_path.stat().st_size, - ) -content_uri = upload_response.content_uri -await client.room_send(room_id, "m.room.message", { - "msgtype": "m.file", # or m.image, m.audio, m.video - "body": filename, - "url": content_uri, -}) +# Source: current repo pattern + Matrix spec +await client.room_put_state( + room_id=space_id, + event_type="m.space.child", + content={"via": [homeserver]}, + state_key=chat_room_id, +) ``` -### YAML config extension (target format) +### Persist room-scoped attachment paths +```python +# Source: adapter/matrix/files.py +relative_path, absolute_path = build_workspace_attachment_path( + workspace_root=workspace_root, + matrix_user_id=matrix_user_id, + room_id=room_id, + filename=filename, +) +absolute_path.parent.mkdir(parents=True, exist_ok=True) +absolute_path.write_bytes(body) +``` +### Health-gated startup in Compose ```yaml -# config/matrix-agents.yaml (new format per D-02/D-03) +# Source: Docker Compose docs +services: + matrix-bot: + depends_on: + platform-agent: + condition: service_healthy -user_agents: - "@user0:matrix.lambda.coredump.ru": agent-0 - "@user1:matrix.lambda.coredump.ru": agent-1 - -agents: - - id: agent-0 - label: "Agent 0" - base_url: "ws://lambda.coredump.ru:7000/agent_0/" - workspace_path: "/agents/0/" - - - id: agent-1 - label: "Agent 1" - base_url: "ws://lambda.coredump.ru:7000/agent_1/" - workspace_path: "/agents/1/" + platform-agent: + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8000/health"] + interval: 10s + timeout: 5s + retries: 5 ``` ---- +## State of the Art -## Runtime State Inventory +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| Per-user or single shared platform context | Per-room `platform_chat_id` | Repo direction corrected on 2026-04-28 | Enables true room isolation and correct `!clear` | +| Single overloaded compose runtime | Separate prod handoff and full-stack E2E compose files | Current Phase 05 scope | Reduces operator ambiguity | +| Unknown room auto-bootstrap as recovery | Explicit reconciliation before live traffic | Recommended for Phase 05 | Prevents duplicate chat trees after restart | +| File payloads treated as transport concern | Shared-volume relative path contract | Already present in repo | Keeps bot/platform contract simple and durable | -> Phase includes refactoring but NOT renaming of string identifiers in user-facing data. Users interacting with the old multi-room bot will have SQLite room_meta records with old schema keys. +**Deprecated/outdated:** +- Single-chat / DM-first deployment direction: explicitly discarded in Phase 05 reset. +- Global reset semantics for Matrix context commands: does not match Space+rooms UX. +- Using only local store as truth for restart recovery: unsafe once deployed rooms outlive the process. -| Category | Items Found | Action Required | -|----------|-------------|------------------| -| Stored data (SQLite) | `lambda_matrix.db` (dev). Room meta records contain `chat_id: "C1"`, `space_id`, `redirect_room_id`, `agent_id` — from old multi-room flow. | No migration. D-05 says: ignore existing Space+rooms, do not migrate. New users get DM-first. Old users' DM rooms will lack `welcomed` key — first message in DM room triggers normal message dispatch path (acceptable). | -| Stored data (SQLite) | `selected_agent_id` key in user metadata — written by `!agent` command being deleted. | No migration needed. `!agent` is gone. The new routing uses `user_agents` from YAML config. Old `selected_agent_id` values are orphaned but harmless. | -| Live service config | No external services with stored config (no n8n, no Datadog). | None. | -| OS-registered state | None. Bot runs in Docker, no launchd/systemd registration. | None. | -| Secrets/env vars | `AGENT_BASE_URL` (global) → replaced by per-agent `base_url` in YAML. `SURFACES_WORKSPACE_DIR` (global workspace) → per-agent `workspace_path` from YAML. Both env vars become deprecated for prod but remain for backward compat in dev. | Update `.env.example`. Add `.env.prod` template. | -| Build artifacts | None in prod context. Local: `.venv`, `__pycache__` — unaffected. | None. | +## Open Questions ---- +1. **What exact Matrix state should reconciliation trust for `chat_id` labels?** + - What we know: `room_meta.chat_id` is local and not derivable from Matrix protocol by default. + - What's unclear: whether chat labels should be reconstructed from room names, stored custom state, or cached local metadata when present. + - Recommendation: persist `chat_id` in local SQLite, but make reconciliation able to regenerate a stable fallback label and avoid blocking routing if the label is missing. -## Validation Architecture +2. **What readiness probe exists for `platform-agent` in the full-stack compose?** + - What we know: Compose health gating is the right pattern. + - What's unclear: whether upstream agent image already exposes a reliable health endpoint. + - Recommendation: inspect upstream container and add a bot-facing probe before finalizing `docker-compose.fullstack.yml`. -### Test Framework - -| Property | Value | -|----------|-------| -| Framework | pytest 9.0.2 + pytest-asyncio | -| Config file | `pyproject.toml` (`asyncio_mode = "auto"`) | -| Quick run command | `uv run pytest tests/adapter/matrix/ -q` | -| Full suite command | `uv run pytest tests/ -q` | - -### Current Test Status (pre-Phase-05) - -| File | Status | Disposition in Phase 05 | -|------|--------|-------------------------| -| test_converter.py | 14 passing | Keep as-is | -| test_files.py | 2 passing | Update for new path format | -| test_reactions.py | 2 passing | Keep as-is | -| test_restart_persistence.py | 5 passing | Keep; update if routing logic changes | -| test_routing_enforcement.py | 5 passing | Update for user_agents routing model | -| test_store.py | 2 passing | Keep as-is | -| test_agent_handler.py | failing (import?) | DELETE — !agent is deleted | -| test_agent_registry.py | failing (import?) | REWRITE — test new AgentDefinition schema | -| test_chat_space.py | failing | DELETE — Space provisioning deleted | -| test_confirm.py | failing | Keep or update | -| test_context_commands.py | 4 failing | REWRITE — !save/!load deleted; keep !context, add !clear | -| test_dispatcher.py | 20 failing | REWRITE — DM-first flow replaces multi-room | -| test_invite_space.py | 3 failing | DELETE and REPLACE with DM-first invite tests | -| test_routed_platform.py | 1 failing | REWRITE — user_agents lookup replaces room binding | -| test_send_outgoing.py | failing | REWRITE — per-agent workspace_path | - -### Phase Requirements → Test Map - -| Behavior | Test Type | Automated Command | Wave | -|----------|-----------|-------------------|------| -| AgentRegistry parses new YAML format (user_agents + base_url/workspace_path) | unit | `uv run pytest tests/adapter/matrix/test_agent_registry.py -x` | Wave 1 | -| Unauthorized user gets access-denied message on invite | unit | `uv run pytest tests/adapter/matrix/test_invite_dm.py -x` | Wave 2 | -| Authorized user gets welcome on DM invite | unit | `uv run pytest tests/adapter/matrix/test_invite_dm.py -x` | Wave 2 | -| Message from authorized user routes to correct delegate | unit | `uv run pytest tests/adapter/matrix/test_routed_platform.py -x` | Wave 2 | -| Incoming file saved to `incoming/{filename}` under agent workspace | unit | `uv run pytest tests/adapter/matrix/test_files.py -x` | Wave 3 | -| !clear command returns "Контекст сброшен." | unit | `uv run pytest tests/adapter/matrix/test_context_commands.py -x` | Wave 2 | -| Full suite green | integration | `uv run pytest tests/ -q` | Phase gate | - -### Wave 0 Gaps - -- [ ] `tests/adapter/matrix/test_invite_dm.py` — DM-first invite flow (new file) -- [ ] Updated `tests/adapter/matrix/test_agent_registry.py` — new schema - -*(All other existing test infrastructure is in place. No new framework install needed.)* - ---- +3. **Should prod mount root remain `/workspace` or be renamed to `/agents` externally?** + - What we know: current code defaults to `SURFACES_WORKSPACE_DIR=/workspace`, while deployment docs describe shared `/agents/`. + - What's unclear: whether external handoff wants a host path named `/agents` while containers still use `/workspace`. + - Recommendation: keep one in-container canonical path and let host-side naming vary only in Compose mounts. ## Environment Availability | Dependency | Required By | Available | Version | Fallback | |------------|------------|-----------|---------|----------| -| uv / Python 3.11 | tests, bot run | ✓ | Python 3.11.9, pytest 9.0.2 | — | -| Docker | docker-compose.prod.yml | ✓ (assumed dev machine) | — | Manual install | -| matrix-nio | Matrix adapter | ✓ | installed in .venv | — | -| pyyaml | agent_registry.py | ✓ | installed (yaml import works in bot context) | — | -| lambda-agent:latest image | docker-compose.prod.yml | ✗ | placeholder — platform team owns | Use `build: ./external/platform-agent` for local testing | +| Python | bot runtime | ✓ | 3.14.3 | — | +| `uv` | dependency install | ✓ | 0.9.30 | `pip` | +| `pytest` | validation | ✓ | 9.0.2 installed | `python -m pytest` | +| Docker Engine | deployment packaging / E2E compose | ✓ | 29.1.3 | none | +| Docker Compose | split runtime orchestration | ✓ | 2.40.3 | none | **Missing dependencies with no fallback:** -- `lambda-agent:latest` — docker-compose.prod.yml uses this as placeholder image. For actual testing, use `build: ./external/platform-agent` fallback or `image: busybox` stub. +- None ---- +**Missing dependencies with fallback:** +- None -## Open Questions +## Validation Architecture -1. **is_direct detection for group room rejection (D-05, Claude's Discretion)** - - What we know: matrix-nio's `InviteMemberEvent` does not expose `is_direct` flag directly. The `MatrixRoom` type has member count accessible via `room.member_count` or `room.joined_members`. - - What's unclear: Whether InviteMemberEvent or MatrixRoom in nio exposes enough to reliably detect DM vs. group at invite time. - - Recommendation: At Phase 05, accept all invites and immediately check user_agents authorization. Non-DM group rooms where the bot is invited by an authorized user will also work (no harm). Add `room.member_count <= 2` check if desired. +### Test Framework +| Property | Value | +|----------|-------| +| Framework | `pytest` + `pytest-asyncio` | +| Config file | `pyproject.toml` | +| Quick run command | `pytest tests/adapter/matrix/test_restart_persistence.py -v` | +| Full suite command | `pytest tests/ -v` | -2. **True !clear semantics with MemorySaver** - - What we know: `RealPlatformClient._build_chat_api` creates a new `AgentApi(chat_id="0")` per request. The agent's `MemorySaver` is keyed by `chat_id` — always `"0"`. So context is NOT cleared by reconnecting. - - What's unclear: Whether `!clear` should work "for real" (requires platform to support a reset endpoint or different chat_id) or just show a user-facing message (MVP-acceptable). - - Recommendation: Phase 05 sends "Контекст сброшен." immediately (D-11). Document the limitation. Actual context reset is a platform concern. +### Phase Requirements → Test Map +| Req ID | Behavior | Test Type | Automated Command | File Exists? | +|--------|----------|-----------|-------------------|-------------| +| PH05-01 | Space+rooms onboarding remains primary UX | integration | `pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py -v` | ✅ | +| PH05-02 | Per-room `platform_chat_id` isolates routing and powers real clear | integration | `pytest tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_context_commands.py -v` | ✅ | +| PH05-03 | Restart reconciliation restores routing metadata | integration | `pytest tests/adapter/matrix/test_restart_persistence.py -v` | ❌ new reconciliation tests needed | +| PH05-04 | Shared-volume file transfer is room-safe | integration | `pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v` | ✅ partial | +| PH05-05 | Split prod/fullstack compose artifacts stay coherent | smoke | `docker compose -f docker-compose.prod.yml config && docker compose -f docker-compose.fullstack.yml config` | ❌ Wave 0 | -3. **lambda-agent:latest image name** - - What we know: D-08 says "placeholder image `lambda-agent:latest` — уточнить у Азамата". - - Recommendation: Use `lambda-agent:latest` as image name in docker-compose.prod.yml. Add a comment indicating it's a placeholder. Provide `build:` fallback pointing to `./external/platform-agent` for local dev validation. +### Sampling Rate +- **Per task commit:** `pytest tests/adapter/matrix/test_restart_persistence.py -v` +- **Per wave merge:** `pytest tests/adapter/matrix/ -v` +- **Phase gate:** `pytest tests/ -v` plus both compose files passing `docker compose ... config` ---- - -## Assumptions Log - -| # | Claim | Section | Risk if Wrong | -|---|-------|---------|---------------| -| A1 | `lambda-agent:latest` is the agreed image name for the agent container | docker-compose section | docker-compose.prod.yml won't work; easy to fix by updating image name | -| A2 | Group room invite detection is not required for Phase 05 (DM-first only means "start in DM", not "reject group invites") | DM-first onboarding | If group room rejection IS required, need to investigate matrix-nio InviteMemberEvent structure | -| A3 | !clear in Phase 05 is cosmetic (shows "cleared" but MemorySaver persists until agent restart) | !clear section | User confusion if they expect real context reset | - ---- - -## Project Constraints (from CLAUDE.md) - -| Directive | Implication for Phase 05 | -|-----------|--------------------------| -| Вызовы платформы — через `platform/interface.py` (Protocol) | RealPlatformClient stays the SDK boundary; AgentApi is internal to sdk/ | -| При подключении реального SDK — меняем только `platform/mock.py` | Phase 05 touches `sdk/real.py` for workspace_path — acceptable, it's a refinement not a rewrite | -| Хотфиксы (< 20 строк) → Claude Code напрямую, не Codex | Phase 05 is >20 lines; must go through Codex via GSD | -| Реализацию делает codex:rescue | Plans must be PLAN.md format passable to Codex | -| Никогда не коммить `.env` | `.env.prod` must be in `.gitignore` — only `.env.prod.example` is committed | -| `uv sync` для зависимостей | No new pip installs; all deps already in pyproject.toml | -| pytest tests/ для тестов | Phase gate: `uv run pytest tests/ -q` must be green | - ---- +### Wave 0 Gaps +- [ ] `tests/adapter/matrix/test_reconciliation.py` — startup recovery of user/room metadata from Matrix state +- [ ] `tests/adapter/matrix/test_context_commands.py` additions — `!clear` command contract and room-local rotation semantics +- [ ] `tests/adapter/matrix/test_compose_artifacts.py` or equivalent smoke command documentation — split compose validation +- [ ] `tests/adapter/matrix/test_files.py` additions — cross-room attachment path isolation and shared-root consistency ## Sources ### Primary (HIGH confidence) -- [VERIFIED: adapter/matrix/agent_registry.py] — current AgentDefinition/AgentRegistry structure -- [VERIFIED: adapter/matrix/bot.py] — _build_platform_from_env, MatrixBot, handle_invite, _materialize_incoming_attachments -- [VERIFIED: adapter/matrix/routed_platform.py] — _resolve_delegate logic -- [VERIFIED: adapter/matrix/files.py] — build_workspace_attachment_path, download_matrix_attachment -- [VERIFIED: adapter/matrix/handlers/agent.py] — !agent handler (to be deleted) -- [VERIFIED: adapter/matrix/handlers/auth.py] — provision_workspace_chat (to be replaced) -- [VERIFIED: adapter/matrix/handlers/context_commands.py] — !save/!load/!reset handlers -- [VERIFIED: adapter/matrix/handlers/__init__.py] — handler registration -- [VERIFIED: sdk/real.py] — RealPlatformClient, _build_chat_api, _attachment_from_send_file_event -- [VERIFIED: sdk/upstream_agent_api.py] — sys.path patching, AgentApi import -- [VERIFIED: external/platform-agent_api/lambda_agent_api/agent_api.py] — actual AgentApi implementation -- [VERIFIED: config/matrix-agents.yaml] — current format -- [VERIFIED: docker-compose.yml] — existing dev compose topology -- [VERIFIED: .env.example] — current env var set -- [VERIFIED: docs/deploy-architecture.md] — prod topology spec -- [VERIFIED: .planning/phases/05-mvp-deployment/05-CONTEXT.md] — locked decisions +- Local repo code and tests: + - `adapter/matrix/bot.py` + - `adapter/matrix/store.py` + - `adapter/matrix/files.py` + - `adapter/matrix/routed_platform.py` + - `adapter/matrix/handlers/auth.py` + - `adapter/matrix/handlers/context_commands.py` + - `tests/adapter/matrix/test_restart_persistence.py` + - `tests/adapter/matrix/test_files.py` + - `tests/platform/test_real.py` +- Matrix-nio API docs: https://matrix-nio.readthedocs.io/en/latest/nio.html +- Matrix-nio async client docs: https://matrix-nio.readthedocs.io/en/latest/_modules/nio/client/async_client.html +- Matrix-nio PyPI release page: https://pypi.org/project/matrix-nio/ +- Matrix spec Spaces / hierarchy: https://spec.matrix.org/v1.18/server-server-api/ +- Matrix spec changelog note on `via` for `m.space.child`: https://spec.matrix.org/v1.16/changelog/v1.9/ +- Docker Compose CLI reference: https://docs.docker.com/reference/cli/docker/compose/ +- Docker Compose services reference: https://docs.docker.com/reference/compose-file/services/ ### Secondary (MEDIUM confidence) -- [ASSUMED: A1] lambda-agent image name — from CONTEXT.md D-08 description -- [ASSUMED: A2] Group room handling scope — inferred from D-05 wording +- `docs/deploy-architecture.md` — repo-local deployment contract clarified on 2026-04-27 +- `docs/research/matrix-spaces.md` — prior internal research aligned with spec, but not treated as primary +- `README.md` runtime notes for current Matrix backend and shared workspace behavior ---- +### Tertiary (LOW confidence) +- None ## Metadata **Confidence breakdown:** -- Standard stack: HIGH — all libraries verified in existing code -- Architecture patterns: HIGH — all patterns verified against actual source files -- Pitfalls: HIGH — all pitfalls derived from reading actual code, not from training assumptions -- Test strategy: HIGH — test files enumerated and statuses verified by running pytest +- Standard stack: HIGH - current repo stack verified against official docs and package registries +- Architecture: HIGH - recommendations align with existing runtime boundaries and official Matrix / Compose behavior +- Pitfalls: HIGH - derived from current code paths, existing tests, and official protocol/runtime semantics -**Research date:** 2026-04-27 -**Valid until:** 2026-05-27 (stable codebase; short-circuit if platform-agent_api changes) +**Research date:** 2026-04-28 +**Valid until:** 2026-05-28 From cafb0ec9e4a9c4ece0a6f5fcb3e7af449fbb932b Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:04:31 +0300 Subject: [PATCH 29/55] test(05-03): add failing shared-volume attachment contract tests - cover room-safe Matrix inbox paths under /agents workspaces - assert /workspace and /agents file paths normalize to relative workspace paths --- tests/adapter/matrix/test_files.py | 17 +++++++++++++++ tests/platform/test_real.py | 35 ++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/tests/adapter/matrix/test_files.py b/tests/adapter/matrix/test_files.py index 831ca72..71fb02f 100644 --- a/tests/adapter/matrix/test_files.py +++ b/tests/adapter/matrix/test_files.py @@ -48,3 +48,20 @@ async def test_download_matrix_attachment_persists_file_and_returns_workspace_pa assert saved.workspace_path is not None assert saved.workspace_path.endswith("20260420-153000-report.pdf") assert (tmp_path / saved.workspace_path).read_bytes() == b"%PDF-1.7" + + +def test_build_workspace_attachment_path_keeps_room_safe_agents_relative_contract(tmp_path: Path): + rel_path, abs_path = build_workspace_attachment_path( + workspace_root=tmp_path / "agents" / "7", + matrix_user_id="@alice+bob:example.org", + room_id="!room/ops:example.org", + filename="quarterly status (final).pdf", + timestamp="20260420-153000", + ) + + assert rel_path == ( + "surfaces/matrix/alice_bob_example.org/room_ops_example.org/inbox/" + "20260420-153000-quarterly_status_final_.pdf" + ) + assert not Path(rel_path).is_absolute() + assert abs_path == tmp_path / "agents" / "7" / rel_path diff --git a/tests/platform/test_real.py b/tests/platform/test_real.py index 7a2e37e..81a73b2 100644 --- a/tests/platform/test_real.py +++ b/tests/platform/test_real.py @@ -190,6 +190,7 @@ async def test_real_platform_client_forwards_attachments_to_chat_api(): agent_api = FakeAgentApiFactory(chat_api_cls=AttachmentTrackingChatAgentApi) client = make_real_platform_client(agent_api) attachment = Attachment( + url="/agents/7/surfaces/matrix/alice/room/inbox/report.pdf", workspace_path="surfaces/matrix/alice/room/inbox/report.pdf", mime_type="application/pdf", filename="report.pdf", @@ -210,6 +211,20 @@ async def test_real_platform_client_forwards_attachments_to_chat_api(): assert result.tokens_used == 0 +def test_attachment_paths_normalize_workspace_roots_to_relative_paths(): + attachments = [ + Attachment(workspace_path="/workspace/output/report.pdf"), + Attachment(workspace_path="/agents/7/output/report.csv"), + Attachment(workspace_path="surfaces/matrix/alice/room/inbox/note.txt"), + ] + + assert RealPlatformClient._attachment_paths(attachments) == [ + "output/report.pdf", + "output/report.csv", + "surfaces/matrix/alice/room/inbox/note.txt", + ] + + @pytest.mark.asyncio async def test_real_platform_client_preserves_send_file_events_in_sync_result(monkeypatch): class FileEventAgentApi(AttachmentTrackingChatAgentApi): @@ -239,6 +254,26 @@ async def test_real_platform_client_preserves_send_file_events_in_sync_result(mo ] +@pytest.mark.parametrize( + ("location", "expected_workspace_path"), + [ + ("/workspace/output/report.pdf", "output/report.pdf"), + ("/agents/7/output/report.pdf", "output/report.pdf"), + ("surfaces/matrix/alice/room/inbox/report.pdf", "surfaces/matrix/alice/room/inbox/report.pdf"), + ], +) +def test_attachment_from_send_file_event_normalizes_shared_volume_paths( + location: str, expected_workspace_path: str +): + attachment = RealPlatformClient._attachment_from_send_file_event( + MsgEventSendFile(path=location) + ) + + assert attachment.url == location + assert attachment.workspace_path == expected_workspace_path + assert attachment.filename == "report.pdf" + + @pytest.mark.asyncio async def test_real_platform_client_uses_fresh_agent_connection_per_request(): agent_api = FakeAgentApiFactory() From 9a0316076a220e4a1e5256ddeffc86af987413b4 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:05:15 +0300 Subject: [PATCH 30/55] fix(05-03): normalize shared-volume attachment paths - strip /workspace and /agents roots before forwarding attachments upstream - reuse the same normalization for send-file events returned to Matrix --- sdk/real.py | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/sdk/real.py b/sdk/real.py index 792c6c1..bf432d9 100644 --- a/sdk/real.py +++ b/sdk/real.py @@ -191,6 +191,27 @@ class RealPlatformClient(PlatformClient): code = getattr(exc, "code", None) or "PLATFORM_CONNECTION_ERROR" return PlatformError(str(exc), code=code) + @staticmethod + def _normalize_workspace_path(location: str) -> str | None: + if not location: + return None + + path = Path(location) + if not path.is_absolute(): + normalized = path.as_posix() + return normalized or None + + parts = path.parts + if len(parts) >= 2 and parts[1] == "workspace": + relative = Path(*parts[2:]).as_posix() + return relative or None + if len(parts) >= 3 and parts[1] == "agents": + relative = Path(*parts[3:]).as_posix() + return relative or None + + relative = path.as_posix().lstrip("/") + return relative or None + @staticmethod def _attachment_paths(attachments: list[Attachment] | None) -> list[str]: if not attachments: @@ -198,18 +219,18 @@ class RealPlatformClient(PlatformClient): paths = [] for attachment in attachments: if attachment.workspace_path: - paths.append(attachment.workspace_path) + normalized = RealPlatformClient._normalize_workspace_path( + attachment.workspace_path + ) + if normalized: + paths.append(normalized) return paths @staticmethod def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment: location = str(event.path) filename = Path(location).name or None - workspace_path = location - if workspace_path.startswith("/workspace/"): - workspace_path = workspace_path[len("/workspace/") :] - elif workspace_path == "/workspace": - workspace_path = "" + workspace_path = RealPlatformClient._normalize_workspace_path(location) return Attachment( url=location, mime_type="application/octet-stream", From a75b26a1cb3d81086976eb3a36276419a3b9f1be Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:05:59 +0300 Subject: [PATCH 31/55] test(05-01): add restart reconciliation regression coverage - add startup reconciliation tests for recovery, idempotence, and startup ordering - extend restart persistence coverage for legacy platform_chat_id backfill --- tests/adapter/matrix/test_reconciliation.py | 203 ++++++++++++++++++ .../matrix/test_restart_persistence.py | 60 +++++- 2 files changed, 260 insertions(+), 3 deletions(-) create mode 100644 tests/adapter/matrix/test_reconciliation.py diff --git a/tests/adapter/matrix/test_reconciliation.py b/tests/adapter/matrix/test_reconciliation.py new file mode 100644 index 0000000..3732bbc --- /dev/null +++ b/tests/adapter/matrix/test_reconciliation.py @@ -0,0 +1,203 @@ +from __future__ import annotations + +import importlib +from types import SimpleNamespace +from unittest.mock import AsyncMock + +from adapter.matrix.bot import MatrixBot, build_runtime +from adapter.matrix.reconciliation import reconcile_startup_state +from adapter.matrix.store import get_room_meta, get_user_meta, set_room_meta, set_user_meta +from sdk.mock import MockPlatformClient + + +def _room( + room_id: str, + name: str, + members: list[str], + *, + parents: tuple[str, ...] = (), +): + return SimpleNamespace( + room_id=room_id, + name=name, + display_name=name, + users={user_id: SimpleNamespace(user_id=user_id) for user_id in members}, + space_parents=set(parents), + ) + + +async def test_reconcile_startup_state_restores_space_room_and_chat_bindings(): + runtime = build_runtime(platform=MockPlatformClient()) + client = SimpleNamespace( + user_id="@bot:example.org", + rooms={ + "!space:example.org": _room( + "!space:example.org", + "Lambda - Alice", + ["@bot:example.org", "@alice:example.org"], + ), + "!chat3:example.org": _room( + "!chat3:example.org", + "Чат 3", + ["@bot:example.org", "@alice:example.org"], + parents=("!space:example.org",), + ), + }, + ) + + await reconcile_startup_state(client, runtime) + + user_meta = await get_user_meta(runtime.store, "@alice:example.org") + assert user_meta is not None + assert user_meta["space_id"] == "!space:example.org" + assert user_meta["next_chat_index"] == 4 + + room_meta = await get_room_meta(runtime.store, "!chat3:example.org") + assert room_meta is not None + assert room_meta["room_type"] == "chat" + assert room_meta["chat_id"] == "C3" + assert room_meta["space_id"] == "!space:example.org" + assert room_meta["matrix_user_id"] == "@alice:example.org" + assert room_meta["platform_chat_id"] == "1" + + chats = await runtime.chat_mgr.list_active("@alice:example.org") + assert [chat.chat_id for chat in chats] == ["C3"] + assert [chat.surface_ref for chat in chats] == ["!chat3:example.org"] + + +async def test_reconcile_startup_state_is_idempotent_with_existing_local_state(): + runtime = build_runtime(platform=MockPlatformClient()) + client = SimpleNamespace( + user_id="@bot:example.org", + rooms={ + "!space:example.org": _room( + "!space:example.org", + "Lambda - Alice", + ["@bot:example.org", "@alice:example.org"], + ), + "!chat3:example.org": _room( + "!chat3:example.org", + "Чат 3", + ["@bot:example.org", "@alice:example.org"], + parents=("!space:example.org",), + ), + }, + ) + await set_user_meta( + runtime.store, + "@alice:example.org", + {"space_id": "!space:example.org", "next_chat_index": 8}, + ) + await set_room_meta( + runtime.store, + "!chat3:example.org", + { + "room_type": "chat", + "chat_id": "C3", + "display_name": "Existing name", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + "platform_chat_id": "42", + }, + ) + await runtime.chat_mgr.get_or_create( + user_id="@alice:example.org", + chat_id="C3", + platform="matrix", + surface_ref="!chat3:example.org", + name="Existing name", + ) + + await reconcile_startup_state(client, runtime) + await reconcile_startup_state(client, runtime) + + user_meta = await get_user_meta(runtime.store, "@alice:example.org") + assert user_meta == {"space_id": "!space:example.org", "next_chat_index": 8} + + room_meta = await get_room_meta(runtime.store, "!chat3:example.org") + assert room_meta is not None + assert room_meta["display_name"] == "Existing name" + assert room_meta["platform_chat_id"] == "42" + + chats = await runtime.chat_mgr.list_active("@alice:example.org") + assert len(chats) == 1 + assert chats[0].chat_id == "C3" + + +async def test_reconciliation_prevents_lazy_bootstrap_for_existing_room(): + runtime = build_runtime(platform=MockPlatformClient()) + client = SimpleNamespace( + user_id="@bot:example.org", + rooms={ + "!space:example.org": _room( + "!space:example.org", + "Lambda - Alice", + ["@bot:example.org", "@alice:example.org"], + ), + "!chat3:example.org": _room( + "!chat3:example.org", + "Чат 3", + ["@bot:example.org", "@alice:example.org"], + parents=("!space:example.org",), + ), + }, + room_send=AsyncMock(), + ) + bot = MatrixBot(client=client, runtime=runtime) + bot._bootstrap_unregistered_room = AsyncMock() + runtime.dispatcher.dispatch = AsyncMock(return_value=[]) + + await reconcile_startup_state(client, runtime) + await bot.on_room_message( + SimpleNamespace(room_id="!chat3:example.org"), + SimpleNamespace(sender="@alice:example.org", body="hello"), + ) + + bot._bootstrap_unregistered_room.assert_not_awaited() + runtime.dispatcher.dispatch.assert_awaited_once() + + +async def test_matrix_main_runs_reconciliation_before_sync_forever(monkeypatch): + bot_module = importlib.import_module("adapter.matrix.bot") + + runtime = SimpleNamespace(platform=SimpleNamespace(close=AsyncMock())) + call_order: list[str] = [] + + class FakeAsyncClient: + def __init__(self, *args, **kwargs): + self.access_token = None + self.callbacks = [] + self.close = AsyncMock() + self.sync_forever = AsyncMock(side_effect=self._sync_forever) + + async def _sync_forever(self, *args, **kwargs): + call_order.append("sync_forever") + + async def login(self, *args, **kwargs): + raise AssertionError("login should not be called when access token is provided") + + def add_event_callback(self, callback, event_type): + self.callbacks.append((callback, event_type)) + + async def fake_prepare_live_sync(client): + call_order.append("prepare_live_sync") + return "s123" + + async def fake_reconcile_startup_state(client, runtime): + call_order.append("reconcile_startup_state") + + monkeypatch.setenv("MATRIX_HOMESERVER", "https://matrix.example.org") + monkeypatch.setenv("MATRIX_USER_ID", "@bot:example.org") + monkeypatch.setenv("MATRIX_ACCESS_TOKEN", "token") + monkeypatch.setattr(bot_module, "AsyncClient", FakeAsyncClient) + monkeypatch.setattr(bot_module, "build_runtime", lambda **kwargs: runtime) + monkeypatch.setattr(bot_module, "prepare_live_sync", fake_prepare_live_sync) + monkeypatch.setattr(bot_module, "reconcile_startup_state", fake_reconcile_startup_state) + + await bot_module.main() + + assert call_order == [ + "prepare_live_sync", + "reconcile_startup_state", + "sync_forever", + ] diff --git a/tests/adapter/matrix/test_restart_persistence.py b/tests/adapter/matrix/test_restart_persistence.py index 492a94a..e2a1f96 100644 --- a/tests/adapter/matrix/test_restart_persistence.py +++ b/tests/adapter/matrix/test_restart_persistence.py @@ -1,16 +1,18 @@ from __future__ import annotations -import pytest +from types import SimpleNamespace -from core.store import SQLiteStore +from adapter.matrix.bot import build_runtime +from adapter.matrix.reconciliation import reconcile_startup_state from adapter.matrix.store import ( - PLATFORM_CHAT_SEQ_KEY, get_room_meta, get_selected_agent_id, next_platform_chat_id, set_room_meta, set_selected_agent_id, ) +from core.store import SQLiteStore +from sdk.mock import MockPlatformClient async def test_selected_agent_id_survives_restart(tmp_path): @@ -73,3 +75,55 @@ async def test_missing_durable_store_starts_clean(tmp_path): store = SQLiteStore(db) assert await get_selected_agent_id(store, "@nobody:example.org") is None assert await get_room_meta(store, "!nonexistent:example.org") is None + + +async def test_startup_reconciliation_backfills_legacy_platform_chat_id_before_restart_routes( + tmp_path, +): + db = str(tmp_path / "state.db") + store = SQLiteStore(db) + await set_room_meta( + store, + "!chat2:example.org", + { + "room_type": "chat", + "chat_id": "C2", + "display_name": "Чат 2", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + }, + ) + + runtime = build_runtime(platform=MockPlatformClient(), store=store) + client = SimpleNamespace( + user_id="@bot:example.org", + rooms={ + "!space:example.org": SimpleNamespace( + room_id="!space:example.org", + name="Lambda - Alice", + display_name="Lambda - Alice", + users={ + "@bot:example.org": SimpleNamespace(user_id="@bot:example.org"), + "@alice:example.org": SimpleNamespace(user_id="@alice:example.org"), + }, + space_parents=set(), + ), + "!chat2:example.org": SimpleNamespace( + room_id="!chat2:example.org", + name="Чат 2", + display_name="Чат 2", + users={ + "@bot:example.org": SimpleNamespace(user_id="@bot:example.org"), + "@alice:example.org": SimpleNamespace(user_id="@alice:example.org"), + }, + space_parents={"!space:example.org"}, + ), + }, + ) + + await reconcile_startup_state(client, runtime) + + store2 = SQLiteStore(db) + room_meta = await get_room_meta(store2, "!chat2:example.org") + assert room_meta is not None + assert room_meta["platform_chat_id"] == "1" From 6693d72cbd59a1e66ff94e54109a68d75b11d123 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:07:35 +0300 Subject: [PATCH 32/55] docs(05-03): complete shared-volume attachment hardening plan - add 05-03 summary with task commits and verification details - update roadmap and state for completed Phase 05 plan 03 --- .planning/ROADMAP.md | 23 ++++ .planning/STATE.md | 38 +++---- .../phases/05-mvp-deployment/05-03-SUMMARY.md | 103 ++++++++++++++++++ 3 files changed, 145 insertions(+), 19 deletions(-) create mode 100644 .planning/phases/05-mvp-deployment/05-03-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e81178c..b27bdb1 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -64,6 +64,29 @@ Plans: --- +### Phase 05: MVP Deployment + +**Goal:** Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru без потери Space+rooms UX: закрепить per-room `platform_chat_id`, реальный `!clear`, reconciliation, file transfer через shared volume и разделение prod/fullstack compose. + +**Depends on:** Phase 4 + +**Plans:** 1/4 plans executed + +Plans: +- [ ] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync +- [ ] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics +- [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment +- [ ] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs + +**Deliverables:** +- Space+rooms onboarding remains the primary Matrix UX +- Per-room `platform_chat_id` provides true context isolation and `!clear` +- Reconciliation restores room metadata and routing after restart +- File transfer uses shared `/agents/` volume with room-safe behavior +- `docker-compose.prod.yml` is bot-only handoff; `docker-compose.fullstack.yml` is for internal E2E testing + +--- + ### Phase 3: Production Hardening **Goal:** Подготовить боты к реальному деплою — конфиг, логирование, мониторинг, обработка ошибок. diff --git a/.planning/STATE.md b/.planning/STATE.md index 5d87f69..5c8e4ce 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,14 +2,13 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Phase 04 complete — deployment architecture clarified, Phase 05 ready to plan -last_updated: "2026-04-27T18:44:51Z" +status: Executing Phase 05 +last_updated: "2026-04-27T22:06:43.419Z" progress: - total_phases: 5 + total_phases: 6 completed_phases: 2 - total_plans: 12 - completed_plans: 9 - percent: 75 + total_plans: 16 + completed_plans: 10 --- # State @@ -19,21 +18,18 @@ progress: See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра -**Current focus:** Phase 04 multi-agent routing follow-up fully implemented; ready for live validation or Phase 05 planning +**Current focus:** Phase 05 — mvp-deployment ## Current Phase -**Phase 4** implementation complete: Matrix MVP + multi-agent routing +**Phase 05** in progress: MVP deployment hardening -All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-direct-agent-prototype`: +Plan `05-03` is complete. Shared-volume attachment handling now keeps Matrix file references room-safe on disk and relative across the `/agents` deployment boundary. -- `7627012` / `242f4aa` / `9ccba16` — agent registry loader, RoutedPlatformClient facade, fail-fast on missing registry in real mode -- `a65227e` — dispatch chat_id contract alignment -- `74cf028` — `!agent` command, `selected_agent_id` persistence, unbound-room binding on first selection -- `7623039` — attachment normalization in core message handler -- `e733119` — stale room blocking, `agent_id` binding on `!new`, durable restart state tests +- `cafb0ec` — failing regressions for `/agents` workspace paths and send-file normalization +- `9a03160` — runtime normalization of `/workspace` and `/agents` absolute paths back to relative `workspace_path` values -135 Matrix tests pass. The branch is ready for review and merge. +Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. ## Decisions @@ -60,6 +56,9 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d - [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient). - [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata. - [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test. +- [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts. +- [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references. +- [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering. ## Blockers @@ -72,7 +71,7 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d - Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT) - Phase 4 added: Matrix MVP: shared agent context and context management command - Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence) -- New platform signal: upcoming proper `chat_id` support should enable file-level context separation and stronger context management in a future follow-up phase. +- Phase 05 reset on 2026-04-28: erroneous single-chat deployment artifacts were removed before fresh planning. ## Performance Metrics @@ -88,9 +87,10 @@ All 5 tasks of the multi-agent routing follow-up are committed on `feat/matrix-d | 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 | | 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | | 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | +| 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | ## Session -- Last session: 2026-04-24T14:10:00Z -- Stopped at: Deployment architecture clarified with platform team; docs/deploy-architecture.md written; Phase 05 ready to plan -- Resume file: .planning/.continue-here.md +- Last session: 2026-04-27T22:06:43Z +- Stopped at: Completed 05-03-PLAN.md +- Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md new file mode 100644 index 0000000..0745e7c --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-03-SUMMARY.md @@ -0,0 +1,103 @@ +--- +phase: 05-mvp-deployment +plan: 03 +subsystem: infra +tags: [matrix, attachments, shared-volume, agents, pytest] +requires: + - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma + provides: direct AgentApi integration and Matrix outgoing file rendering +provides: + - shared-volume attachment path regressions for /agents deployment + - relative workspace-path normalization for upstream attachment transport + - send-file event normalization for Matrix outbound file rendering +affects: [matrix, deployment, shared-volume, file-transfer] +tech-stack: + added: [] + patterns: [relative workspace_path transport, shared-volume root normalization] +key-files: + created: [] + modified: + - tests/adapter/matrix/test_files.py + - tests/platform/test_real.py + - sdk/real.py +key-decisions: + - "Keep adapter/matrix/files.py as the only path-construction source; sdk/real.py only normalizes attachment references crossing the shared-volume boundary." + - "Normalize both /workspace and /agents absolute paths back to relative workspace paths before forwarding to the agent API or rendering Matrix send-file events." +patterns-established: + - "Matrix attachment transport stays relative even when the bot sees absolute shared-volume paths." + - "Agent-emitted file paths are rendered back to Matrix without HTTP proxy shims or inline blobs." +requirements-completed: [PH05-04] +duration: 3 min +completed: 2026-04-27 +--- + +# Phase 05 Plan 03: Shared-volume attachment path hardening Summary + +**Room-safe Matrix inbox paths and relative shared-volume attachment normalization for `/agents` deployment** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-04-27T22:02:34Z +- **Completed:** 2026-04-27T22:05:41Z +- **Tasks:** 2 +- **Files modified:** 3 + +## Accomplishments +- Added regression coverage for room-safe `surfaces/matrix/.../inbox/...` attachment layout under `/agents` workspaces. +- Added explicit tests for `/workspace/...` and `/agents/...` attachment-path normalization on both upstream send and downstream send-file rendering. +- Tightened `RealPlatformClient` so only relative `workspace_path` values are forwarded to the agent API. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add shared-volume file contract tests for `/agents` deployment** - `cafb0ec` (test) +2. **Task 2: Tighten attachment path handling for the shared volume contract** - `9a03160` (fix) + +## Files Created/Modified +- `tests/adapter/matrix/test_files.py` - covers room-safe shared-volume inbox paths under an `/agents` workspace root. +- `tests/platform/test_real.py` - covers relative attachment forwarding and send-file normalization for `/workspace` and `/agents` paths. +- `sdk/real.py` - normalizes shared-volume roots before attachments cross the upstream or Matrix rendering boundary. + +## Decisions Made +- Kept `adapter/matrix/files.py` unchanged so path construction remains centralized there. +- Reused one normalization helper in `sdk/real.py` for both `_attachment_paths()` and `_attachment_from_send_file_event()` to keep inbound and outbound behavior aligned. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Adjusted verification to use the project uv environment** +- **Found during:** Task 2 (Tighten attachment path handling for the shared volume contract) +- **Issue:** The plan's raw `pytest` command collected with an interpreter missing `PyYAML`, which blocked `tests/adapter/matrix/test_send_outgoing.py` before runtime assertions could execute. +- **Fix:** Re-ran verification with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest ...`, matching the repo's `CLAUDE.md` guidance and the project `.venv`. +- **Files modified:** None +- **Verification:** `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v` +- **Committed in:** None (verification-environment adjustment only) + +--- + +**Total deviations:** 1 auto-fixed (1 blocking) +**Impact on plan:** No scope creep. The deviation only changed the verification entrypoint so the planned test slice could run in the correct environment. + +## Issues Encountered +- The ambient `pytest` resolved to a different virtualenv than the project `.venv`, so direct verification was unreliable for dependency-backed Matrix tests. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Shared-volume file references now stay relative across inbound bot downloads, agent API attachment transport, and outbound Matrix send-file rendering. +- Phase 05 compose and deployment work can assume the `/agents` contract without adding file proxy infrastructure. + +## Self-Check: PASSED + +- Found `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md` +- Verified commit `cafb0ec` exists in git history +- Verified commit `9a03160` exists in git history + +--- +*Phase: 05-mvp-deployment* +*Completed: 2026-04-27* From 8a80d004fdb1b9f97a3dcb57dcfe9fd351d47e89 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:08:15 +0300 Subject: [PATCH 33/55] feat(05-01): reconcile matrix rooms before live sync - rebuild room and user metadata from synced space topology at startup - run reconciliation before sync_forever and persist legacy platform_chat_id backfills --- adapter/matrix/bot.py | 2 + adapter/matrix/reconciliation.py | 150 +++++++++++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 adapter/matrix/reconciliation.py diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index cf8adb1..e35e92b 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -37,6 +37,7 @@ from adapter.matrix.handlers.context_commands import ( LOAD_PROMPT, ) from adapter.matrix.routed_platform import RoutedPlatformClient +from adapter.matrix.reconciliation import reconcile_startup_state from adapter.matrix.room_router import resolve_chat_id from adapter.matrix.store import ( add_staged_attachment, @@ -746,6 +747,7 @@ async def main() -> None: await client.login(password=password, device_name="surfaces-bot") since_token = await prepare_live_sync(client) + await reconcile_startup_state(client, runtime) bot = MatrixBot(client, runtime) client.add_event_callback( diff --git a/adapter/matrix/reconciliation.py b/adapter/matrix/reconciliation.py new file mode 100644 index 0000000..fcf24e5 --- /dev/null +++ b/adapter/matrix/reconciliation.py @@ -0,0 +1,150 @@ +from __future__ import annotations + +import re +from dataclasses import dataclass + +from adapter.matrix.store import ( + get_room_meta, + get_user_meta, + next_platform_chat_id, + set_room_meta, + set_user_meta, +) + +_CHAT_ID_PATTERNS = ( + re.compile(r"\bC(?P\d+)\b", re.IGNORECASE), + re.compile(r"^Чат\s+(?P\d+)$", re.IGNORECASE), +) + + +@dataclass(slots=True) +class ReconciliationResult: + recovered_rooms: int = 0 + repaired_rooms: int = 0 + backfilled_platform_chat_ids: int = 0 + + +def _room_name(room: object) -> str | None: + for attr in ("name", "display_name"): + value = getattr(room, attr, None) + if isinstance(value, str) and value.strip(): + return value.strip() + return None + + +def _chat_id_from_room(room: object, existing_meta: dict | None) -> str | None: + chat_id = (existing_meta or {}).get("chat_id") + if isinstance(chat_id, str) and chat_id: + return chat_id + + name = _room_name(room) + if not name: + return None + + for pattern in _CHAT_ID_PATTERNS: + match = pattern.search(name) + if match: + return f"C{int(match.group('index'))}" + return None + + +def _space_id_for_room(room: object, rooms_by_id: dict[str, object], existing_meta: dict | None) -> str | None: + existing_space_id = (existing_meta or {}).get("space_id") + if isinstance(existing_space_id, str) and existing_space_id: + return existing_space_id + + parents = getattr(room, "parents", None) + if not parents: + parents = getattr(room, "space_parents", None) + if not parents: + return None + + for parent_id in parents: + parent = rooms_by_id.get(parent_id) + if parent is None: + continue + if getattr(parent, "room_type", None) == "m.space" or getattr(parent, "children", None): + return parent_id + return parent_id + return None + + +def _matrix_user_id_for_room(room: object, bot_user_id: str | None, existing_meta: dict | None) -> str | None: + existing_user_id = (existing_meta or {}).get("matrix_user_id") + if isinstance(existing_user_id, str) and existing_user_id: + return existing_user_id + + users = getattr(room, "users", None) or {} + for user_id in users: + if user_id != bot_user_id: + return user_id + return None + + +async def reconcile_startup_state(client: object, runtime: object) -> ReconciliationResult: + rooms_by_id = getattr(client, "rooms", None) or {} + bot_user_id = getattr(client, "user_id", None) + result = ReconciliationResult() + max_chat_index_by_user: dict[str, int] = {} + recovered_space_by_user: dict[str, str] = {} + + for room_id, room in rooms_by_id.items(): + if getattr(room, "room_type", None) == "m.space": + continue + + existing_meta = await get_room_meta(runtime.store, room_id) + if existing_meta and existing_meta.get("redirect_room_id"): + continue + + space_id = _space_id_for_room(room, rooms_by_id, existing_meta) + chat_id = _chat_id_from_room(room, existing_meta) + matrix_user_id = _matrix_user_id_for_room(room, bot_user_id, existing_meta) + if not space_id or not chat_id or not matrix_user_id: + continue + + recovered_space_by_user[matrix_user_id] = space_id + chat_index = int(chat_id[1:]) + max_chat_index_by_user[matrix_user_id] = max( + max_chat_index_by_user.get(matrix_user_id, 0), + chat_index, + ) + + display_name = (existing_meta or {}).get("display_name") or _room_name(room) or chat_id + room_meta = dict(existing_meta or {}) + room_meta.update( + { + "room_type": "chat", + "chat_id": chat_id, + "display_name": display_name, + "matrix_user_id": matrix_user_id, + "space_id": space_id, + } + ) + + if not room_meta.get("platform_chat_id"): + room_meta["platform_chat_id"] = await next_platform_chat_id(runtime.store) + result.backfilled_platform_chat_ids += 1 + + if existing_meta is None: + result.recovered_rooms += 1 + elif room_meta != existing_meta: + result.repaired_rooms += 1 + + await set_room_meta(runtime.store, room_id, room_meta) + await runtime.auth_mgr.confirm(matrix_user_id) + await runtime.chat_mgr.get_or_create( + user_id=matrix_user_id, + chat_id=chat_id, + platform="matrix", + surface_ref=room_id, + name=display_name, + ) + + for matrix_user_id, recovered_space_id in recovered_space_by_user.items(): + user_meta = dict(await get_user_meta(runtime.store, matrix_user_id) or {}) + user_meta["space_id"] = user_meta.get("space_id") or recovered_space_id + next_chat_index = max_chat_index_by_user[matrix_user_id] + 1 + user_meta["next_chat_index"] = max(int(user_meta.get("next_chat_index", 1)), next_chat_index) + await set_user_meta(runtime.store, matrix_user_id, user_meta) + + return result From ae37476ddf8f9ac6bdcef52a42b0f57f27cc8b89 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:13:54 +0300 Subject: [PATCH 34/55] test(05-02): add failing regressions for clear routing - cover room-local clear rotation and upstream disconnect behavior - assert strict routed-platform failures on incomplete room bindings --- tests/adapter/matrix/test_context_commands.py | 92 ++++++++++++++++++- tests/adapter/matrix/test_routed_platform.py | 80 ++++++++++++++++ 2 files changed, 171 insertions(+), 1 deletion(-) diff --git a/tests/adapter/matrix/test_context_commands.py b/tests/adapter/matrix/test_context_commands.py index a289772..9264a06 100644 --- a/tests/adapter/matrix/test_context_commands.py +++ b/tests/adapter/matrix/test_context_commands.py @@ -1,11 +1,12 @@ from __future__ import annotations from types import SimpleNamespace -from unittest.mock import AsyncMock +from unittest.mock import AsyncMock, Mock import pytest from adapter.matrix.bot import MatrixBot, build_runtime +from adapter.matrix.handlers import register_matrix_handlers from adapter.matrix.handlers.context_commands import ( make_handle_context, make_handle_load, @@ -29,6 +30,7 @@ class MatrixCommandPlatform(MockPlatformClient): super().__init__() self._prototype_state = PrototypeStateStore() self._agent_api = object() + self.disconnect_chat = AsyncMock() self.send_message = AsyncMock( return_value=MessageResponse( message_id="msg-1", @@ -39,6 +41,12 @@ class MatrixCommandPlatform(MockPlatformClient): ) +@pytest.fixture(autouse=True) +def clear_matrix_registry_env(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("MATRIX_AGENT_REGISTRY_PATH", raising=False) + monkeypatch.delenv("MATRIX_PLATFORM_BACKEND", raising=False) + + @pytest.mark.asyncio async def test_save_command_auto_name_records_session(): platform = MatrixCommandPlatform() @@ -179,6 +187,88 @@ async def test_reset_command_assigns_new_platform_chat_id(): assert "сброшен" in result[0].text.lower() +@pytest.mark.asyncio +async def test_clear_command_rotates_only_current_room_and_disconnects_old_upstream_chat(): + from adapter.matrix.store import get_platform_chat_id + + platform = MatrixCommandPlatform() + runtime = build_runtime(platform=platform) + await runtime.chat_mgr.get_or_create( + user_id="u1", + chat_id="C1", + platform="matrix", + surface_ref="!room-a:example.org", + name="Chat A", + ) + await runtime.chat_mgr.get_or_create( + user_id="u1", + chat_id="C2", + platform="matrix", + surface_ref="!room-b:example.org", + name="Chat B", + ) + await set_room_meta( + runtime.store, + "!room-a:example.org", + {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41"}, + ) + await set_room_meta( + runtime.store, + "!room-b:example.org", + {"chat_id": "C2", "matrix_user_id": "u1", "platform_chat_id": "99"}, + ) + + handler = make_handle_reset(store=runtime.store, prototype_state=platform._prototype_state) + event = IncomingCommand( + user_id="u1", + platform="matrix", + chat_id="C1", + command="clear", + args=[], + ) + + result = await handler( + event, + runtime.auth_mgr, + platform, + runtime.chat_mgr, + runtime.settings_mgr, + ) + + room_a_chat_id = await get_platform_chat_id(runtime.store, "!room-a:example.org") + room_b_chat_id = await get_platform_chat_id(runtime.store, "!room-b:example.org") + assert room_a_chat_id == "1" + assert room_a_chat_id != "41" + assert room_b_chat_id == "99" + platform.disconnect_chat.assert_awaited_once_with("41") + assert "сброшен" in result[0].text.lower() + + +def test_register_matrix_handlers_exposes_clear_and_optional_reset_alias(): + dispatcher = SimpleNamespace(register=Mock()) + + register_matrix_handlers( + dispatcher, + client=object(), + store=object(), + registry=None, + prototype_state=PrototypeStateStore(), + ) + + clear_calls = [ + call + for call in dispatcher.register.call_args_list + if call.args[:2] == (IncomingCommand, "clear") + ] + reset_calls = [ + call + for call in dispatcher.register.call_args_list + if call.args[:2] == (IncomingCommand, "reset") + ] + assert clear_calls + assert len(reset_calls) <= 1 + + @pytest.mark.asyncio async def test_context_command_shows_current_snapshot(): platform = MatrixCommandPlatform() diff --git a/tests/adapter/matrix/test_routed_platform.py b/tests/adapter/matrix/test_routed_platform.py index 1aa3400..c3efca5 100644 --- a/tests/adapter/matrix/test_routed_platform.py +++ b/tests/adapter/matrix/test_routed_platform.py @@ -14,6 +14,7 @@ from core.chat import ChatManager from core.store import InMemoryStore from sdk.interface import MessageChunk, MessageResponse, User, UserSettings from sdk.mock import MockPlatformClient +from sdk.interface import PlatformError class FakeDelegate: @@ -99,6 +100,12 @@ class FakeDelegate: self.update_calls.append((user_id, action)) +@pytest.fixture(autouse=True) +def clear_matrix_registry_env(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("MATRIX_AGENT_REGISTRY_PATH", raising=False) + monkeypatch.delenv("MATRIX_PLATFORM_BACKEND", raising=False) + + @pytest.mark.asyncio async def test_send_message_routes_by_room_agent_and_platform_chat_id(): store = InMemoryStore() @@ -159,6 +166,79 @@ async def test_stream_message_routes_by_room_agent_and_platform_chat_id(): ] +@pytest.mark.asyncio +async def test_send_message_fails_fast_when_platform_chat_id_is_missing(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org") + await set_room_meta( + store, + "!room:example.org", + {"agent_id": "agent-2"}, + ) + platform = RoutedPlatformClient( + chat_mgr=chat_mgr, + store=store, + delegates={"agent-2": FakeDelegate(name="agent-2")}, + ) + + with pytest.raises(PlatformError, match="routing is incomplete") as exc_info: + await platform.send_message("u1", "C1", "hello") + + assert exc_info.value.code == "MATRIX_ROUTE_INCOMPLETE" + + +@pytest.mark.asyncio +async def test_stream_message_fails_fast_when_agent_id_is_missing(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org") + await set_room_meta( + store, + "!room:example.org", + {"platform_chat_id": "41"}, + ) + platform = RoutedPlatformClient( + chat_mgr=chat_mgr, + store=store, + delegates={"agent-2": FakeDelegate(name="agent-2")}, + ) + + with pytest.raises(PlatformError, match="routing is incomplete") as exc_info: + await anext(platform.stream_message("u1", "C1", "hello")) + + assert exc_info.value.code == "MATRIX_ROUTE_INCOMPLETE" + + +@pytest.mark.asyncio +async def test_routing_uses_repaired_room_metadata_without_runtime_backfill(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org") + await set_room_meta( + store, + "!room:example.org", + {"platform_chat_id": "restored-41", "agent_id": "agent-2"}, + ) + delegate = FakeDelegate(name="agent-2") + platform = RoutedPlatformClient( + chat_mgr=chat_mgr, + store=store, + delegates={"agent-2": delegate}, + ) + + await platform.send_message("u1", "C1", "hello") + + assert delegate.send_calls == [ + { + "user_id": "u1", + "chat_id": "restored-41", + "text": "hello", + "attachments": None, + } + ] + + @pytest.mark.asyncio async def test_user_and_settings_delegate_to_default_client(): store = InMemoryStore() From df6d8bf62895e48bbacda95b82ee9b946ca62d27 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:14:05 +0300 Subject: [PATCH 35/55] feat(05-04): split prod and fullstack compose artifacts - add bot-only production compose contract - add health-gated internal fullstack harness --- .env.example | 13 +++++++--- docker-compose.fullstack.yml | 49 ++++++++++++++++++++++++++++++++++++ docker-compose.prod.yml | 21 ++++++++++++++++ 3 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 docker-compose.fullstack.yml create mode 100644 docker-compose.prod.yml diff --git a/.env.example b/.env.example index e251708..e8c2e88 100644 --- a/.env.example +++ b/.env.example @@ -8,11 +8,16 @@ MATRIX_PASSWORD=your_password_here MATRIX_PLATFORM_BACKEND=real MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml -# Shared workspace contract -SURFACES_WORKSPACE_DIR=/workspace +# Shared /agents contract for Phase 05 deployment +SURFACES_WORKSPACE_DIR=/agents +SURFACES_SHARED_VOLUME=surfaces-agents -# Compose-local platform-agent route -AGENT_BASE_URL=http://platform-agent:8000 +# Production handoff: point the bot at the externally managed agent endpoint. +AGENT_BASE_URL=https://lambda.coredump.ru/agent_0/ + +# Internal full-stack compose defaults +AGENT_ID=matrix-dev +COMPOSIO_API_KEY= # platform-agent provider PROVIDER_MODEL=openai/gpt-4o-mini diff --git a/docker-compose.fullstack.yml b/docker-compose.fullstack.yml new file mode 100644 index 0000000..1128d30 --- /dev/null +++ b/docker-compose.fullstack.yml @@ -0,0 +1,49 @@ +services: + matrix-bot: + extends: + file: docker-compose.prod.yml + service: matrix-bot + environment: + AGENT_BASE_URL: http://platform-agent:8000 + depends_on: + platform-agent: + condition: service_healthy + + platform-agent: + build: + context: ./external/platform-agent + target: development + additional_contexts: + agent_api: ./external/platform-agent_api + environment: + PYTHONUNBUFFERED: "1" + AGENT_ID: ${AGENT_ID:-matrix-dev} + PROVIDER_MODEL: ${PROVIDER_MODEL:-openai/gpt-4o-mini} + PROVIDER_URL: ${PROVIDER_URL:-} + PROVIDER_API_KEY: ${PROVIDER_API_KEY:-} + COMPOSIO_API_KEY: ${COMPOSIO_API_KEY:-} + volumes: + - ./external/platform-agent/src:/app/src + - ./external/platform-agent_api:/agent_api + - agents:/workspace + command: > + sh -lc " + mkdir -p /workspace && + chown -R agent:agent /workspace && + exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 + " + ports: + - "8000:8000" + healthcheck: + test: + - CMD-SHELL + - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()" + interval: 10s + timeout: 5s + retries: 5 + start_period: 10s + restart: unless-stopped + +volumes: + agents: + name: ${SURFACES_SHARED_VOLUME:-surfaces-agents} diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml new file mode 100644 index 0000000..2316d2f --- /dev/null +++ b/docker-compose.prod.yml @@ -0,0 +1,21 @@ +services: + matrix-bot: + build: . + environment: + MATRIX_HOMESERVER: ${MATRIX_HOMESERVER:-} + MATRIX_USER_ID: ${MATRIX_USER_ID:-} + MATRIX_PASSWORD: ${MATRIX_PASSWORD:-} + MATRIX_ACCESS_TOKEN: ${MATRIX_ACCESS_TOKEN:-} + MATRIX_PLATFORM_BACKEND: ${MATRIX_PLATFORM_BACKEND:-real} + MATRIX_AGENT_REGISTRY_PATH: ${MATRIX_AGENT_REGISTRY_PATH:-config/matrix-agents.yaml} + AGENT_BASE_URL: ${AGENT_BASE_URL:-} + SURFACES_WORKSPACE_DIR: ${SURFACES_WORKSPACE_DIR:-/agents} + PYTHONUNBUFFERED: "1" + volumes: + - agents:/agents + - ./config:/app/config:ro + restart: unless-stopped + +volumes: + agents: + name: ${SURFACES_SHARED_VOLUME:-surfaces-agents} From 85e2fda6bc9632bebcfcdff909d7b6404ddc3f04 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:15:39 +0300 Subject: [PATCH 36/55] feat(05-02): ship room-local clear semantics - register clear as the room-context reset entrypoint when supported - keep save and context bound to room platform chat ids and clear old upstream state --- adapter/matrix/handlers/__init__.py | 13 +++--- adapter/matrix/handlers/context_commands.py | 48 ++++++++++++++------- 2 files changed, 39 insertions(+), 22 deletions(-) diff --git a/adapter/matrix/handlers/__init__.py b/adapter/matrix/handlers/__init__.py index 7484a37..6d8c3f1 100644 --- a/adapter/matrix/handlers/__init__.py +++ b/adapter/matrix/handlers/__init__.py @@ -47,13 +47,12 @@ def register_matrix_handlers( dispatcher.register(IncomingCommand, "archive", make_handle_archive(client, store)) dispatcher.register(IncomingCommand, "help", handle_help) dispatcher.register(IncomingCommand, "settings", handle_settings) - dispatcher.register( - IncomingCommand, - "reset", - make_handle_reset(store, prototype_state) - if prototype_state is not None - else handle_settings, - ) + if prototype_state is not None: + clear_handler = make_handle_reset(store, prototype_state) + dispatcher.register(IncomingCommand, "clear", clear_handler) + dispatcher.register(IncomingCommand, "reset", clear_handler) + else: + dispatcher.register(IncomingCommand, "reset", handle_settings) dispatcher.register(IncomingCommand, "settings_skills", handle_settings_skills) dispatcher.register(IncomingCommand, "settings_connectors", handle_settings_connectors) dispatcher.register(IncomingCommand, "settings_soul", handle_settings_soul) diff --git a/adapter/matrix/handlers/context_commands.py b/adapter/matrix/handlers/context_commands.py index 648978d..121d76b 100644 --- a/adapter/matrix/handlers/context_commands.py +++ b/adapter/matrix/handlers/context_commands.py @@ -59,6 +59,17 @@ async def _resolve_context_scope( return room_id, platform_chat_id +async def _require_platform_context( + event: IncomingCommand, + store: StateStore, + chat_mgr, +) -> tuple[str, str]: + room_id, platform_chat_id = await _resolve_context_scope(event, store, chat_mgr) + if not platform_chat_id: + raise RuntimeError(f"matrix room context is incomplete: {room_id}") + return room_id, platform_chat_id + + def make_handle_save(agent_api, store: StateStore, prototype_state: PrototypeStateStore): async def handle_save( event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr @@ -85,11 +96,16 @@ def make_handle_save(agent_api, store: StateStore, prototype_state: PrototypeSta logger.warning("save_agent_call_failed", error=str(exc)) return [OutgoingMessage(chat_id=event.chat_id, text=f"Ошибка при сохранении: {exc}")] - _, platform_chat_id = await _resolve_context_scope(event, store, chat_mgr) + try: + _, platform_chat_id = await _require_platform_context(event, store, chat_mgr) + except RuntimeError as exc: + logger.warning("save_context_incomplete", error=str(exc)) + return [OutgoingMessage(chat_id=event.chat_id, text="Контекст комнаты не готов. Попробуй позже.")] + await prototype_state.add_saved_session( event.user_id, name, - source_context_id=platform_chat_id or event.chat_id, + source_context_id=platform_chat_id, ) return [ OutgoingMessage( @@ -132,9 +148,11 @@ def make_handle_reset(store: StateStore, prototype_state: PrototypeStateStore): async def handle_reset( event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr ) -> list[OutgoingEvent]: - room_id = await _resolve_room_id(event, chat_mgr) - room_meta = await get_room_meta(store, room_id) - old_chat_id = (room_meta or {}).get("platform_chat_id") or room_id + try: + room_id, old_chat_id = await _require_platform_context(event, store, chat_mgr) + except RuntimeError as exc: + logger.warning("clear_context_incomplete", error=str(exc)) + return [OutgoingMessage(chat_id=event.chat_id, text="Контекст комнаты не готов. Попробуй позже.")] new_chat_id = await next_platform_chat_id(store) await set_platform_chat_id(store, room_id, new_chat_id) @@ -143,6 +161,7 @@ def make_handle_reset(store: StateStore, prototype_state: PrototypeStateStore): if callable(disconnect): await disconnect(old_chat_id) + await prototype_state.clear_current_session(old_chat_id) await prototype_state.clear_current_session(new_chat_id) return [ @@ -182,20 +201,19 @@ def make_handle_context(store: StateStore, prototype_state: PrototypeStateStore) async def handle_context( event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr ) -> list[OutgoingEvent]: - _, platform_chat_id = await _resolve_context_scope(event, store, chat_mgr) - context_key = platform_chat_id or event.chat_id - current_session = await prototype_state.get_current_session(context_key) - tokens_used = await prototype_state.get_last_tokens_used(context_key) - if platform_chat_id is not None and event.chat_id != platform_chat_id: - if current_session is None: - current_session = await prototype_state.get_current_session(event.chat_id) - if tokens_used == 0: - tokens_used = await prototype_state.get_last_tokens_used(event.chat_id) + try: + _, platform_chat_id = await _require_platform_context(event, store, chat_mgr) + except RuntimeError as exc: + logger.warning("context_scope_incomplete", error=str(exc)) + return [OutgoingMessage(chat_id=event.chat_id, text="Контекст комнаты не готов. Попробуй позже.")] + + current_session = await prototype_state.get_current_session(platform_chat_id) + tokens_used = await prototype_state.get_last_tokens_used(platform_chat_id) sessions = await prototype_state.list_saved_sessions(event.user_id) lines = [ "Контекст:", - f" Контекст чата: {platform_chat_id or event.chat_id}", + f" Контекст чата: {platform_chat_id}", f" Сессия: {current_session or 'не загружена'}", f" Токены (последний ответ): {tokens_used}", f" Сохранения ({len(sessions)}):", From 22a3a2b60a07506b3033dc96e84698e175736a11 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:15:41 +0300 Subject: [PATCH 37/55] docs(05-04): document split deployment artifacts - document prod vs fullstack compose usage - align operator docs with shared /agents contract --- README.md | 41 ++++++++++++++++++++++++------------- docs/deploy-architecture.md | 33 ++++++++++++++++++++--------- 2 files changed, 50 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 24f6c36..b444948 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ | Поверхность | Статус | |---|---| | Telegram | 🔨 В разработке, отдельный worktree `feat/telegram-adapter` | -| Matrix | ✅ Рабочий прототип, запускается через root `docker compose` вместе с `platform-agent` | +| Matrix | ✅ MVP runtime: `docker-compose.prod.yml` для bot-only handoff, `docker-compose.fullstack.yml` для internal E2E | --- @@ -90,7 +90,7 @@ class PlatformClient(Protocol): Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер. Сейчас: `MockPlatformClient` в `sdk/mock.py`, а Matrix real backend собирается через `sdk/real.py` при `MATRIX_PLATFORM_BACKEND=real`. -Файловый контракт уже path-based: бот пишет файлы в shared `/workspace` и передаёт платформе относительные пути в `attachments`. +Файловый контракт уже path-based: бот пишет файлы в shared `/agents` и передаёт платформе относительные пути в `attachments`, которые агент читает внутри своего `/workspace`. Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем. --- @@ -121,9 +121,13 @@ MATRIX_PASSWORD=... # или MATRIX_ACCESS_TOKEN=... # Выбор backend: mock (по умолчанию) или real (подключение к platform-agent) MATRIX_PLATFORM_BACKEND=real -# compose runtime: platform-agent service name + shared /workspace -AGENT_BASE_URL=http://platform-agent:8000 -SURFACES_WORKSPACE_DIR=/workspace +# production handoff: bot connects to externally managed agent endpoint +AGENT_BASE_URL=https://lambda.coredump.ru/agent_0/ +SURFACES_WORKSPACE_DIR=/agents +SURFACES_SHARED_VOLUME=surfaces-agents + +# internal full-stack compose defaults +AGENT_ID=matrix-dev # platform-agent provider PROVIDER_MODEL=openai/gpt-4o-mini @@ -137,19 +141,28 @@ PROVIDER_API_KEY=... 2. Если готовишься к multi-agent routing, добавь `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` в `.env` 3. Этот registry сейчас является конфигурационным артефактом Task 1; текущий Matrix runtime его ещё не читает -### 4. Compose runtime +### 4. Compose artifacts -Root `docker-compose.yml` теперь является основным локальным runtime для Matrix и platform-agent. -Он поднимает `matrix-bot`, `platform-agent` и общий volume `/workspace`. +Production handoff uses `docker-compose.prod.yml`. +Этот файл поднимает только `matrix-bot`, монтирует shared volume в `/agents` и ожидает, что `AGENT_BASE_URL` +указывает на уже управляемый внешней платформой agent endpoint. ```bash -docker compose up --build +docker compose --env-file .env -f docker-compose.prod.yml up -d --build ``` -Compose собирает `platform-agent` из актуального upstream `external/platform-agent` Dockerfile (`development` target), -монтирует live-код из `external/platform-agent/src` и `external/platform-agent_api`, и подготавливает shared `/workspace` -с правами для agent runtime. -Matrix бот подключается к `platform-agent` по service name, а не к отдельно запущенному `localhost`. +Internal full-stack E2E uses `docker-compose.fullstack.yml`. +Этот файл поднимает `matrix-bot` вместе с локальным `platform-agent`, использует тот же shared volume +(`SURFACES_SHARED_VOLUME`) и ждёт `service_healthy` вместо sleep-based sequencing. + +```bash +docker compose --env-file .env -f docker-compose.fullstack.yml up --build +``` + +`docker-compose.fullstack.yml` собирает `platform-agent` из актуального upstream `external/platform-agent` +(`development` target), монтирует live-код из `external/platform-agent/src` и `external/platform-agent_api`, +а shared volume виден как `/agents` в bot container и как `/workspace` в `platform-agent`. +Старый root compose harness остаётся только как historical local reference и больше не является рекомендуемым runtime path. На `2026-04-21` локальный compose runtime использует vendored upstream-версии платформы без локальных патчей: @@ -159,7 +172,7 @@ Matrix бот подключается к `platform-agent` по service name, а ### 4. Staged attachments в Matrix Если Matrix-клиент отправляет файлы отдельными media events, бот не вызывает агента сразу. -Вместо этого он сохраняет файлы в shared `/workspace`, ставит их в очередь для конкретного чата и пользователя, и ждёт следующего обычного сообщения. +Вместо этого он сохраняет файлы в shared `/agents`, ставит их в очередь для конкретного чата и пользователя, и ждёт следующего обычного сообщения. Как отправить файлы агенту: diff --git a/docs/deploy-architecture.md b/docs/deploy-architecture.md index 8746e56..3ac891a 100644 --- a/docs/deploy-architecture.md +++ b/docs/deploy-architecture.md @@ -4,6 +4,18 @@ --- +## Compose Artifacts + +- **Production deploy:** `docker-compose.prod.yml` + Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`, требует внешний `AGENT_BASE_URL`. +- **Internal full-stack E2E:** `docker-compose.fullstack.yml` + Внутренний harness. Поднимает `matrix-bot` и `platform-agent`, использует тот же volume name и health-gated startup через `condition: service_healthy`. + +Production operators should run the bot with `docker-compose.prod.yml`; internal verification should use `docker-compose.fullstack.yml`. +Старый root compose harness больше не является primary runtime contract для Phase 05. + +--- + ## Топология ``` @@ -22,7 +34,7 @@ lambda.coredump.ru - **Один инстанс Matrix-бота** обслуживает всех пользователей. - **Один агент-контейнер на пользователя.** Изоляция по agent_id, не через chat_id внутри одного инстанса. -- **Shared volume** `/agents/` смонтирован и в Matrix-бот, и в каждый агент-контейнер. Агент видит свой подкаталог как `/workspace`. +- **Shared volume** `/agents/` смонтирован в Matrix-бот. В internal full-stack harness тот же volume mounted as `/workspace` inside `platform-agent`, чтобы bot-side absolute paths и agent workspace относились к одному и тому же хранилищу. --- @@ -58,24 +70,25 @@ agents: ```python from lambda_agent_api.agent_api import AgentApi -connected_agents: dict[str, AgentApi] = {} +connected_agents: dict[tuple[str, int], AgentApi] = {} def on_agent_disconnect(agent: AgentApi): - del connected_agents[agent.id] + connected_agents.pop((agent.id, agent.chat_id), None) -async def on_message(matrix_user_id: str, text: str): +async def on_message(matrix_user_id: str, matrix_room_id: str, text: str): agent_id = get_agent_id_by_user(matrix_user_id) # из user_agents конфига + platform_chat_id = get_room_platform_chat_id(matrix_room_id) - agent = connected_agents.get(agent_id) + agent = connected_agents.get((agent_id, platform_chat_id)) if not agent: agent = AgentApi( agent_id, get_agent_base_url(agent_id), # ws://lambda.coredump.ru:7000/agent_0/ on_disconnect=on_agent_disconnect, - chat_id=0, # default, один чат на агента + chat_id=platform_chat_id, # отдельный thread на Matrix room ) await agent.connect() - connected_agents[agent_id] = agent + connected_agents[(agent_id, platform_chat_id)] = agent async for event in agent.send_message(text): ... @@ -86,7 +99,7 @@ async def on_message(matrix_user_id: str, text: str): AgentApi( agent_id: str, base_url: str, # ws://host:port/agent_N/ - chat_id: int = 0, # default — один чат на агента + chat_id: int = 0, # surfaces must supply per-room platform_chat_id on_disconnect: callable, ) ``` @@ -111,7 +124,7 @@ AgentApi( 2. Matrix-бот читает файл: `/agents/{N}/output/report.pdf` 3. Отправляет как Matrix file message пользователю -**Ключевое:** поверхность видит `/agents/` целиком через shared volume. Прямой HTTP-доступ к файлам не нужен. +**Ключевое:** production handoff через `docker-compose.prod.yml` и internal E2E через `docker-compose.fullstack.yml` используют один и тот же `/agents` contract на стороне поверхности. Прямой HTTP-доступ к файлам не нужен. --- @@ -140,6 +153,6 @@ AgentApi( ## Что НЕ решено / открытые вопросы - Ветка `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока игнорируем, используем master. Уточнить у Азамата сроки мержа перед деплоем. -- `chat_id` — при нашей модели C1/C2/C3 каждый чат должен иметь отдельный `chat_id`. Нужно решить: один `AgentApi` на агента (chat_id=0) или по инстансу на чат (chat_id=1/2/3). Пока берём `chat_id=0` (один контекст на пользователя). +- `chat_id` — каждый Matrix chat room должен иметь собственный `platform_chat_id`. `!clear` должен ротировать `platform_chat_id` только для текущей комнаты, чтобы получить новый thread и чистый контекст без смены Matrix room. - Composio `AGENT_ID` в `.env` для каждого агента — уточнить у платформы значения. - Что происходит с историей при рестарте агента — `MemorySaver` не персистентный. From e73e13e758c99636d3d4d132560e285876c6eaaf Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:17:48 +0300 Subject: [PATCH 38/55] docs(05-02): complete room-local clear plan - add execution summary for room-local clear and strict routing - update roadmap and state with plan 05-02 completion metadata --- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 32 ++++-- .../phases/05-mvp-deployment/05-02-SUMMARY.md | 106 ++++++++++++++++++ 3 files changed, 133 insertions(+), 13 deletions(-) create mode 100644 .planning/phases/05-mvp-deployment/05-02-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b27bdb1..4e8799b 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -70,13 +70,13 @@ Plans: **Depends on:** Phase 4 -**Plans:** 1/4 plans executed +**Plans:** 4/4 plans complete Plans: -- [ ] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync -- [ ] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics +- [x] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync +- [x] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics - [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment -- [ ] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs +- [x] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs **Deliverables:** - Space+rooms onboarding remains the primary Matrix UX diff --git a/.planning/STATE.md b/.planning/STATE.md index 5c8e4ce..2d48990 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,12 +3,12 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces status: Executing Phase 05 -last_updated: "2026-04-27T22:06:43.419Z" +last_updated: "2026-04-27T22:15:58Z" progress: total_phases: 6 - completed_phases: 2 + completed_phases: 3 total_plans: 16 - completed_plans: 10 + completed_plans: 13 --- # State @@ -24,12 +24,19 @@ See: .planning/PROJECT.md (updated 2026-04-02) **Phase 05** in progress: MVP deployment hardening -Plan `05-03` is complete. Shared-volume attachment handling now keeps Matrix file references room-safe on disk and relative across the `/agents` deployment boundary. +Plan `05-01` is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy `platform_chat_id` bindings on restart. -- `cafb0ec` — failing regressions for `/agents` workspace paths and send-file normalization -- `9a03160` — runtime normalization of `/workspace` and `/agents` absolute paths back to relative `workspace_path` values +- `a75b26a` — failing restart reconciliation regressions for recovery, idempotence, startup ordering, and legacy backfill +- `8a80d00` — startup reconciliation module and pre-sync wiring in the Matrix runtime -Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. +Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v`. + +Plan `05-02` is complete. Matrix room-local context commands now rely on repaired per-room `platform_chat_id` bindings, and `!clear` rotates only the active room's upstream context when prototype room state is available. + +- `ae37476` — failing regressions for clear registration, room-local rotation, and strict routed-platform metadata requirements +- `85e2fda` — room-local clear semantics, compatibility alias wiring, and strict context resolution without shared chat fallbacks + +Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v`. ## Decisions @@ -59,6 +66,11 @@ Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/tes - [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts. - [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references. - [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering. +- [Phase 05]: Treat synced Matrix topology as authoritative for startup recovery; keep SQLite rebuildable. +- [Phase 05]: Backfill missing platform_chat_id values during startup reconciliation before routed handling begins. +- [Phase 05]: Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias. +- [Phase 05]: Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids. +- [Phase 05]: Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification. ## Blockers @@ -88,9 +100,11 @@ Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/tes | 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | | 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | | 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | +| 05 | 01 | 8 min | 2 | 4 | 2026-04-27T22:09:28Z | +| 05 | 02 | 16 min | 2 | 4 | 2026-04-27T22:15:58Z | ## Session -- Last session: 2026-04-27T22:06:43Z -- Stopped at: Completed 05-03-PLAN.md +- Last session: 2026-04-27T22:15:58Z +- Stopped at: Completed 05-02-PLAN.md - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/05-mvp-deployment/05-02-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-02-SUMMARY.md new file mode 100644 index 0000000..fa4a48c --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-02-SUMMARY.md @@ -0,0 +1,106 @@ +--- +phase: 05-mvp-deployment +plan: 02 +subsystem: matrix +tags: [matrix, routing, context, platform-chat-id, testing] +requires: + - phase: 05-01 + provides: startup reconciliation for room metadata before live routing +provides: + - room-local `!clear` coverage and command registration + - strict room-local context resolution for save/context flows + - fail-fast routed-platform regressions for incomplete room bindings +affects: [matrix-dispatcher, routed-platform, startup-reconciliation] +tech-stack: + added: [] + patterns: [per-room platform context, compatibility alias registration, fail-fast routing] +key-files: + created: [] + modified: + - adapter/matrix/handlers/__init__.py + - adapter/matrix/handlers/context_commands.py + - tests/adapter/matrix/test_context_commands.py + - tests/adapter/matrix/test_routed_platform.py +key-decisions: + - "Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias." + - "Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids." +patterns-established: + - "Matrix room context commands resolve through room metadata repaired at startup, not message-time backfill." + - "Reset semantics rotate one room's upstream chat id and disconnect only that old upstream session." +requirements-completed: [PH05-02] +duration: 16 min +completed: 2026-04-27 +--- + +# Phase 05 Plan 02: Room-local clear and strict Matrix routing Summary + +**Room-local `!clear` command coverage, strict per-room `platform_chat_id` context resolution, and fail-fast Matrix routing regressions** + +## Performance + +- **Duration:** 16 min +- **Started:** 2026-04-27T22:00:00Z +- **Completed:** 2026-04-27T22:15:58Z +- **Tasks:** 2 +- **Files modified:** 4 + +## Accomplishments +- Added RED/GREEN regression coverage for `!clear`, room-local chat-id rotation, and strict routed-platform failure modes. +- Registered `clear` as the supported reset entrypoint when room-context support exists, while preserving `reset` as a compatibility alias. +- Removed shared-context fallbacks from save/context handling and fixed reset to clear the old upstream prototype session before rotation. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Expand room-local context and clear-command tests** - `ae37476` (test) +2. **Task 2: Ship real room-local `!clear` semantics and strict routing** - `85e2fda` (feat) + +## Files Created/Modified +- `adapter/matrix/handlers/__init__.py` - registers `clear` for runtimes with prototype room-context support and keeps `reset` as the compatibility alias. +- `adapter/matrix/handlers/context_commands.py` - requires room-local `platform_chat_id` for save/context/clear flows and disconnects the old upstream context on clear. +- `tests/adapter/matrix/test_context_commands.py` - covers room-local clear rotation, upstream disconnect, and clear registration. +- `tests/adapter/matrix/test_routed_platform.py` - covers incomplete-room fail-fast behavior and repaired metadata routing. + +## Decisions Made +- Exposed `clear` only on runtimes that actually have prototype room-context support so Phase 05 semantics do not break older MVP smoke tests. +- Treated startup-repaired room metadata as the only supported source of `platform_chat_id` for context commands instead of falling back to local chat ids. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Clear path was wiping the new context instead of the old upstream session** +- **Found during:** Task 2 (Ship real room-local `!clear` semantics and strict routing) +- **Issue:** `make_handle_reset()` cleared prototype session state for the newly generated chat id, leaving the previous upstream context intact. +- **Fix:** Cleared prototype state for the old `platform_chat_id` before rotating to the new room-local id, and kept the new context empty as well. +- **Files modified:** `adapter/matrix/handlers/context_commands.py` +- **Verification:** `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v` +- **Committed in:** `85e2fda` + +--- + +**Total deviations:** 1 auto-fixed (1 bug) +**Impact on plan:** The auto-fix was required for correct room-local clear behavior. No scope creep. + +## Issues Encountered +- Plain `pytest` used an environment without `PyYAML`; verification was switched to `uv run pytest` with `UV_CACHE_DIR=/tmp/uv-cache-surfaces`. +- Shared shell env exposed `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml`, which broke unrelated Matrix smoke tests. Verification was run with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND=''` to match the intended mock-runtime test setup. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Matrix room-local clear semantics and routing contracts are now explicit and covered. +- Phase 05 follow-on work can assume startup reconciliation remains the only supported repair path for missing room routing metadata. + +--- +*Phase: 05-mvp-deployment* +*Completed: 2026-04-27* + +## Self-Check: PASSED + +- Found `.planning/phases/05-mvp-deployment/05-02-SUMMARY.md` +- Found commit `ae37476` +- Found commit `85e2fda` From 380961d6e92c5d14fc82f6ec1fbf2eee7d269cab Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:18:47 +0300 Subject: [PATCH 39/55] docs(05-04): complete split deployment artifacts plan - add phase summary for split deployment artifacts - update state with phase 05 completion context --- .planning/STATE.md | 28 ++++-- .../phases/05-mvp-deployment/05-04-SUMMARY.md | 93 +++++++++++++++++++ 2 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 .planning/phases/05-mvp-deployment/05-04-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 2d48990..818b085 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,8 +2,8 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Executing Phase 05 -last_updated: "2026-04-27T22:15:58Z" +status: Phase 05 Complete +last_updated: "2026-04-27T22:17:10.233Z" progress: total_phases: 6 completed_phases: 3 @@ -18,11 +18,11 @@ progress: See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра -**Current focus:** Phase 05 — mvp-deployment +**Current focus:** Phase 05 complete — MVP deployment handoff is ready ## Current Phase -**Phase 05** in progress: MVP deployment hardening +**Phase 05** complete: MVP deployment hardening Plan `05-01` is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy `platform_chat_id` bindings on restart. @@ -38,6 +38,20 @@ Plan `05-02` is complete. Matrix room-local context commands now rely on repaire Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v`. +Plan `05-03` is complete. Shared-volume attachment handling now preserves relative agent paths while tolerating both `/workspace` and `/agents` absolute prefixes during normalization and Matrix file rendering. + +- `7a12a71` — failing regressions for shared-volume path normalization and room-safe attachment handling +- `5eddf16` — `/agents` deployment path hardening for Matrix files and routed platform attachments + +Verified with `uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. + +Plan `05-04` is complete. Production handoff now uses `docker-compose.prod.yml` for a bot-only runtime, while internal end-to-end verification uses `docker-compose.fullstack.yml` with shared `/agents` volume guidance and health-gated startup. + +- `df6d8bf` — split prod and full-stack compose artifacts with the shared `/agents` contract +- `22a3a2b` — operator and deployment docs aligned to the split compose artifacts + +Verified with `docker compose -f docker-compose.prod.yml config`, `docker compose -f docker-compose.fullstack.yml config`, and docs grep checks for `docker-compose.prod.yml`, `docker-compose.fullstack.yml`, and `/agents`. + ## Decisions - Продолжаем с Threaded Mode несмотря на баги Mac клиента (2026-04-02) @@ -71,6 +85,7 @@ Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE - [Phase 05]: Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias. - [Phase 05]: Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids. - [Phase 05]: Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification. +- [Phase 05]: Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same named volume. ## Blockers @@ -102,9 +117,10 @@ Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE | 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | | 05 | 01 | 8 min | 2 | 4 | 2026-04-27T22:09:28Z | | 05 | 02 | 16 min | 2 | 4 | 2026-04-27T22:15:58Z | +| 05 | 04 | 3 min | 2 | 5 | 2026-04-27T22:17:10Z | ## Session -- Last session: 2026-04-27T22:15:58Z -- Stopped at: Completed 05-02-PLAN.md +- Last session: 2026-04-27T22:17:10Z +- Stopped at: Completed 05-04-PLAN.md - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/05-mvp-deployment/05-04-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-04-SUMMARY.md new file mode 100644 index 0000000..68a62c6 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-04-SUMMARY.md @@ -0,0 +1,93 @@ +--- +phase: 05-mvp-deployment +plan: 04 +subsystem: infra +tags: [docker-compose, matrix, deployment, agents, docs] +requires: + - phase: 05-03 + provides: "Shared /agents attachment contract and path normalization for Matrix runtime" +provides: + - "docker-compose.prod.yml bot-only deployment handoff artifact" + - "docker-compose.fullstack.yml internal E2E harness with health-gated platform-agent startup" + - "README and deploy architecture docs aligned to the split compose contract" +affects: [mvp-deployment, operator-handoff, internal-e2e] +tech-stack: + added: [Docker Compose] + patterns: [split-compose-by-operational-intent, shared-agents-volume-contract] +key-files: + created: [docker-compose.prod.yml, docker-compose.fullstack.yml] + modified: [.env.example, README.md, docs/deploy-architecture.md] +key-decisions: + - "Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification." + - "Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same volume." +patterns-established: + - "Production operators use docker-compose.prod.yml and provide an external AGENT_BASE_URL." + - "Internal verification uses docker-compose.fullstack.yml with service_healthy gating instead of sleep-based startup." +requirements-completed: [PH05-05] +duration: 3 min +completed: 2026-04-27 +--- + +# Phase 05 Plan 04: Split deployment artifacts Summary + +**Bot-only production compose handoff plus a separate health-gated full-stack harness aligned to the shared `/agents` volume contract** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-04-27T22:12:42Z +- **Completed:** 2026-04-27T22:16:09Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments +- Added `docker-compose.prod.yml` as the operator-facing bot-only runtime artifact. +- Added `docker-compose.fullstack.yml` for internal E2E runs with `platform-agent` health-gated startup. +- Updated env and deployment docs so `/agents` and the split compose flow are explicit without relying on the old root compose file. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Create split prod and fullstack compose artifacts** - `df6d8bf` (feat) +2. **Task 2: Update deployment docs and operator guidance for the split artifacts** - `22a3a2b` (docs) + +**Plan metadata:** pending final docs commit after state updates + +## Files Created/Modified +- `docker-compose.prod.yml` - bot-only deployment handoff with `/agents` volume contract +- `docker-compose.fullstack.yml` - internal harness extending the bot service and adding health-checked `platform-agent` +- `.env.example` - Phase 05 runtime variables for prod handoff and internal full-stack defaults +- `README.md` - operator-facing instructions for choosing the correct compose artifact +- `docs/deploy-architecture.md` - deployment topology and shared-volume guidance aligned to the split artifacts + +## Decisions Made +- Split deployment packaging by operational intent instead of overloading one compose file for both prod handoff and internal testing. +- Kept the bot’s absolute shared path rooted at `/agents` in docs and env examples while letting the internal `platform-agent` consume the same named volume at `/workspace`. + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered + +- The docs verification grep treated `deploy` inside the filename `docs/deploy-architecture.md` as a false positive when root compose was still named explicitly. The fix was to remove the literal root compose filename from deploy-path wording while keeping the deprecation clear. + +## User Setup Required + +None - no external service configuration required beyond populating `.env` from `.env.example`. + +## Next Phase Readiness + +- Operators now have a bot-only compose artifact for handoff, and developers have a separate internal E2E harness. +- Remaining Phase 05 work can rely on the split runtime contract without reinterpreting deployment docs. + +## Self-Check: PASSED + +- Summary file exists at `.planning/phases/05-mvp-deployment/05-04-SUMMARY.md` +- Commit `df6d8bf` found in git history +- Commit `22a3a2b` found in git history + +--- +*Phase: 05-mvp-deployment* +*Completed: 2026-04-27* From b1aaa210a18bd78a72b046bff2e1bc594a3a5f47 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 03:05:11 +0300 Subject: [PATCH 40/55] =?UTF-8?q?feat(deploy):=20platform=20handoff=20?= =?UTF-8?q?=E2=80=94=20agent=20routing,=20persistence,=20docs=20cleanup?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agent routing: - Remove !agent command and manual agent selection flow - Registry auto-assigns agent from user_agents mapping (fallback: agents[0]) - provision_workspace_chat and !new both write agent_id to room_meta - Reconciliation backfills agent_id from registry on cold start - Fix duplicate agent_id block in auth.py Deployment stability: - Add bot-state named volume to persist lambda_matrix.db and matrix_store - Fix docker-compose.prod.yml duplicate environment: key (was silently losing all Matrix credentials) - Fix MATRIX_AGENT_REGISTRY_PATH to use absolute container path /app/config/... - Add bot-state volume declaration to docker-compose.fullstack.yml Docs and config: - Rewrite README.md for platform handoff (deploy table, working commands only) - Rewrite docs/matrix-prototype.md (remove stale commands and mock descriptions) - Remove !save/!load/!context/!agent from help text and welcome message - Add !clear, !list, !remove, !yes/!no to help text - Clean up .env.example (remove Telegram token, internal vars, real URLs) - Update config/matrix-agents.example.yaml with user_agents section and comments - Add explanatory comment to Dockerfile for --ignore-requires-python - Remove silent uv sync fallbacks in Dockerfile --- .env.example | 39 +- Dockerfile | 10 +- README.md | 339 ++++++------------ adapter/matrix/agent_registry.py | 19 +- adapter/matrix/bot.py | 42 +-- adapter/matrix/handlers/__init__.py | 5 +- adapter/matrix/handlers/agent.py | 78 ---- adapter/matrix/handlers/auth.py | 14 +- adapter/matrix/handlers/chat.py | 13 +- adapter/matrix/handlers/settings.py | 13 +- adapter/matrix/reconciliation.py | 9 + adapter/matrix/store.py | 15 - config/matrix-agents.example.yaml | 23 +- config/matrix-agents.yaml | 6 + docker-compose.fullstack.yml | 8 +- docker-compose.prod.yml | 7 +- docs/matrix-prototype.md | 288 ++++----------- tests/adapter/matrix/test_agent_handler.py | 175 --------- tests/adapter/matrix/test_dispatcher.py | 23 +- .../matrix/test_restart_persistence.py | 17 +- .../matrix/test_routing_enforcement.py | 105 ------ 21 files changed, 311 insertions(+), 937 deletions(-) delete mode 100644 adapter/matrix/handlers/agent.py create mode 100644 config/matrix-agents.yaml delete mode 100644 tests/adapter/matrix/test_agent_handler.py delete mode 100644 tests/adapter/matrix/test_routing_enforcement.py diff --git a/.env.example b/.env.example index e8c2e88..610314e 100644 --- a/.env.example +++ b/.env.example @@ -1,25 +1,24 @@ -# Telegram -TELEGRAM_BOT_TOKEN=your_bot_token_here - -# Matrix -MATRIX_HOMESERVER=https://matrix.org -MATRIX_USER_ID=@bot:matrix.org +# Matrix bot credentials +MATRIX_HOMESERVER=https://matrix.example.org +MATRIX_USER_ID=@lambda-bot:example.org +# Use ONE of: MATRIX_PASSWORD or MATRIX_ACCESS_TOKEN MATRIX_PASSWORD=your_password_here +# MATRIX_ACCESS_TOKEN=your_access_token_here + +# Backend: "real" connects to platform-agent via AgentApi; "mock" uses local stub (testing only) MATRIX_PLATFORM_BACKEND=real -MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml -# Shared /agents contract for Phase 05 deployment +# Path to agent registry inside the container (mounted via ./config:/app/config:ro) +MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml + +# HTTP URL of the platform-agent endpoint +# Production: external agent managed by the platform +# Fullstack E2E: overridden to http://platform-agent:8000 by docker-compose.fullstack.yml +AGENT_BASE_URL=http://your-agent-host:8000 + +# Shared volume path inside the bot container (default: /agents) SURFACES_WORKSPACE_DIR=/agents + +# Docker volume names (created automatically on first run) SURFACES_SHARED_VOLUME=surfaces-agents - -# Production handoff: point the bot at the externally managed agent endpoint. -AGENT_BASE_URL=https://lambda.coredump.ru/agent_0/ - -# Internal full-stack compose defaults -AGENT_ID=matrix-dev -COMPOSIO_API_KEY= - -# platform-agent provider -PROVIDER_MODEL=openai/gpt-4o-mini -PROVIDER_URL=https://openrouter.ai/api/v1 -PROVIDER_API_KEY=sk-or-... +SURFACES_BOT_STATE_VOLUME=surfaces-bot-state diff --git a/Dockerfile b/Dockerfile index 0dbb156..00a6e58 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,15 +13,17 @@ RUN pip install --no-cache-dir uv COPY pyproject.toml uv.lock* ./ # Install project dependencies into the system environment. -RUN uv sync --no-dev --no-install-project --frozen 2>/dev/null || uv sync --no-dev --no-install-project +RUN uv sync --no-dev --no-install-project --frozen # Copy project source after dependency layers. COPY . . -# Install the project itself and keep runtime dependencies in sync. -RUN uv sync --no-dev --frozen 2>/dev/null || uv sync --no-dev +# Install the project itself. +RUN uv sync --no-dev --frozen -# Install lambda_agent_api from the local source tree, bypassing its Python version guard. +# Install lambda_agent_api from the vendored source tree. +# --ignore-requires-python: the package declares python<3.12 but works fine on 3.11; +# the guard exists for its own dev tooling, not the runtime API surface we use. RUN pip install --no-cache-dir --ignore-requires-python /app/external/platform-agent_api CMD ["python", "-m", "adapter.matrix.bot"] diff --git a/README.md b/README.md index b444948..731ef89 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,10 @@ # Lambda Lab 3.0 — Surfaces -Команда поверхностей. Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda. +Matrix-бот для взаимодействия пользователя с AI-агентом Lambda. ## Статус -| Поверхность | Статус | -|---|---| -| Telegram | 🔨 В разработке, отдельный worktree `feat/telegram-adapter` | -| Matrix | ✅ MVP runtime: `docker-compose.prod.yml` для bot-only handoff, `docker-compose.fullstack.yml` для internal E2E | - ---- - -## Концепция - -Пользователь получает персонального AI-агента через привычный мессенджер. -Агент выполняет реальные задачи: разбирает почту, ищет информацию, работает с файлами, управляет календарём. - -**Поверхности** — тонкие клиенты. Вся бизнес-логика на стороне платформы. -Задача команды: сделать интерфейс удобным, надёжным и легко расширяемым. +Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff. --- @@ -28,271 +15,173 @@ surfaces-bot/ core/ — общее ядро, не зависит от транспорта protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...) handler.py — EventDispatcher: IncomingEvent → OutgoingEvent - handlers/ — обработчики по типам событий store.py — StateStore Protocol + InMemoryStore + SQLiteStore - chat.py — ChatManager: метаданные чатов C1/C2/C3 - auth.py — AuthManager: аутентификация - settings.py — SettingsManager: коннекторы, скиллы, SOUL, безопасность + chat.py — ChatManager + auth.py — AuthManager + settings.py — SettingsManager adapter/ - telegram/ — aiogram 3.x адаптер matrix/ — matrix-nio адаптер sdk/ interface.py — PlatformClient Protocol (контракт к SDK) - mock.py — MockPlatformClient (заглушка) + real.py — RealPlatformClient (через AgentApi) + mock.py — MockPlatformClient (заглушка для тестов) + + config/ + matrix-agents.yaml — реестр агентов docs/ — документация - .claude/agents/ — агенты для Claude Code ``` -**Ключевой принцип:** добавить новую поверхность = написать один адаптер-конвертер. -Ядро (`core/`) не трогается. Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md) +Подробнее: [`docs/surface-protocol.md`](docs/surface-protocol.md) --- -## Функционал прототипа +## Деплой -### Telegram ([подробнее](docs/telegram-prototype.md)) - -- **Чаты** — основной Telegram UX сейчас развивается в отдельном worktree `feat/telegram-adapter` -- **Forum Topics mode** — бот умеет подключать forum-группу через `/forum`; чат может быть привязан к отдельной теме -- **DM-режим** — базовый диалог и переключение чатов сохраняются -- **Аутентификация** — привязка Telegram аккаунта к аккаунту платформы -- **Диалог** — typing indicator, передача файлов, подтверждение опасных действий через inline-кнопки -- **Настройки** через `/settings`: коннекторы (Gmail, GitHub, Notion...), скиллы, личность агента (SOUL), безопасность, подписка - -### Matrix ([подробнее](docs/matrix-prototype.md)) - -- **Онбординг** — при первом invite бот создаёт private Space `Lambda — {display_name}` и первую комнату `Чат 1`, сразу приглашая туда пользователя -- **Чаты** — `!new`, `!chats`, `!rename`, `!archive`, `!help`; новые комнаты регистрируются в локальном `ChatManager` -- **Диалог** — сообщения, вложения, подтверждения `!yes` / `!no` и routing через `EventDispatcher` -- **Стабильность** — перед `sync_forever()` бот делает bootstrap sync и стартует с `since`, чтобы не переигрывать старую timeline после рестарта -- **Текущее ограничение** — encrypted DM официально не поддержан; ручное тестирование Matrix ведётся в незашифрованных комнатах и зависит от локального state-store бота -- **Backend selection** — `MATRIX_PLATFORM_BACKEND=mock` остаётся значением по умолчанию; `MATRIX_PLATFORM_BACKEND=real` использует `platform-agent` из compose и upstream `AgentApi` по contract `/v1/agent_ws/{chat_id}/` -- **Ограничения real backend** — локальный runtime использует shared `/workspace`, файлы передаются как относительные пути в `attachments`, а transport layer со стороны `surfaces` использует прямой upstream `platform-agent_api.AgentApi` без локального subclass; prod-default lifecycle открывает отдельное соединение на каждый запрос, но после tool/file flow всё ещё остаётся подтверждённый upstream streaming bug, из-за которого начало ответа может пропадать - ---- - -## Замена SDK - -Вся работа с платформой идёт через `PlatformClient` Protocol: - -```python -class PlatformClient(Protocol): - async def get_or_create_user(self, external_id: str, platform: str, ...) -> User: ... - async def send_message(self, user_id: str, chat_id: str, text: str, ...) -> MessageResponse: ... - async def get_settings(self, user_id: str) -> UserSettings: ... - async def update_settings(self, user_id: str, action: Any) -> None: ... -``` - -Бот не управляет lifecycle контейнеров — это делает Master (платформа). -Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер. - -Сейчас: `MockPlatformClient` в `sdk/mock.py`, а Matrix real backend собирается через `sdk/real.py` при `MATRIX_PLATFORM_BACKEND=real`. -Файловый контракт уже path-based: бот пишет файлы в shared `/agents` и передаёт платформе относительные пути в `attachments`, которые агент читает внутри своего `/workspace`. -Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем. - ---- - -## Запуск Matrix-поверхности - -### 1. Зависимости и тесты - -```bash -uv sync -pytest tests/ -v -``` - -### 2. Переменные окружения +### Переменные окружения ```bash cp .env.example .env ``` -Обязательные переменные: +| Переменная | Обязательна | Описание | +|---|---|---| +| `MATRIX_HOMESERVER` | ✓ | URL Matrix-сервера | +| `MATRIX_USER_ID` | ✓ | `@bot:example.org` | +| `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) | +| `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна | +| `AGENT_BASE_URL` | ✓ | HTTP-URL агента, например `http://platform-agent:8000` | +| `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` | +| `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) | +| `SURFACES_SHARED_VOLUME` | | имя Docker volume (по умолчанию `surfaces-agents`) | -```env -# Matrix аккаунт бота -MATRIX_HOMESERVER=https://matrix.example.org -MATRIX_USER_ID=@lambda-bot:example.org -MATRIX_PASSWORD=... # или MATRIX_ACCESS_TOKEN=... +### Реестр агентов -# Выбор backend: mock (по умолчанию) или real (подключение к platform-agent) -MATRIX_PLATFORM_BACKEND=real +`config/matrix-agents.yaml` — статический маппинг пользователей на агентов: -# production handoff: bot connects to externally managed agent endpoint -AGENT_BASE_URL=https://lambda.coredump.ru/agent_0/ -SURFACES_WORKSPACE_DIR=/agents -SURFACES_SHARED_VOLUME=surfaces-agents +```yaml +user_agents: + "@user0:matrix.lambda.coredump.ru": agent-0 + "@user1:matrix.lambda.coredump.ru": agent-1 -# internal full-stack compose defaults -AGENT_ID=matrix-dev - -# platform-agent provider -PROVIDER_MODEL=openai/gpt-4o-mini -PROVIDER_URL=https://openrouter.ai/api/v1 -PROVIDER_API_KEY=... +agents: + - id: agent-0 + label: "Agent 0" + - id: agent-1 + label: "Agent 1" ``` -### 3. Registry агентов +Если `user_agents` не задан или пользователь не найден — используется первый агент из списка. -1. Скопируй `config/matrix-agents.example.yaml` в `config/matrix-agents.yaml` -2. Если готовишься к multi-agent routing, добавь `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` в `.env` -3. Этот registry сейчас является конфигурационным артефактом Task 1; текущий Matrix runtime его ещё не читает - -### 4. Compose artifacts - -Production handoff uses `docker-compose.prod.yml`. -Этот файл поднимает только `matrix-bot`, монтирует shared volume в `/agents` и ожидает, что `AGENT_BASE_URL` -указывает на уже управляемый внешней платформой agent endpoint. +### Production (bot-only) ```bash docker compose --env-file .env -f docker-compose.prod.yml up -d --build ``` -Internal full-stack E2E uses `docker-compose.fullstack.yml`. -Этот файл поднимает `matrix-bot` вместе с локальным `platform-agent`, использует тот же shared volume -(`SURFACES_SHARED_VOLUME`) и ждёт `service_healthy` вместо sleep-based sequencing. +Поднимает только `matrix-bot`. Монтирует shared volume в `/agents`. Требует внешний `AGENT_BASE_URL`. + +### Fullstack E2E (bot + agent) ```bash docker compose --env-file .env -f docker-compose.fullstack.yml up --build ``` -`docker-compose.fullstack.yml` собирает `platform-agent` из актуального upstream `external/platform-agent` -(`development` target), монтирует live-код из `external/platform-agent/src` и `external/platform-agent_api`, -а shared volume виден как `/agents` в bot container и как `/workspace` в `platform-agent`. -Старый root compose harness остаётся только как historical local reference и больше не является рекомендуемым runtime path. +Поднимает `matrix-bot` вместе с локальным `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте. -На `2026-04-21` локальный compose runtime использует vendored upstream-версии платформы без локальных патчей: - -- `platform-agent`: `5e7c2df954cc3cd2f5bf8ae688e10a20038dde61` -- `platform-agent_api`: `8a4f4db6d36786fe8af7feefffe506d4a54ac6bd` - -### 4. Staged attachments в Matrix - -Если Matrix-клиент отправляет файлы отдельными media events, бот не вызывает агента сразу. -Вместо этого он сохраняет файлы в shared `/agents`, ставит их в очередь для конкретного чата и пользователя, и ждёт следующего обычного сообщения. - -Как отправить файлы агенту: - -1. Отправь один или несколько файлов в рабочую Matrix-комнату. -2. При необходимости проверь очередь командой `!list`. -3. Напиши обычное текстовое сообщение, например: - - `что на изображении?` - - `прочитай pdf и сделай summary` - - `сравни эти два файла` -4. Это сообщение уйдёт агенту вместе со всеми staged файлами из очереди. - -Команды: - -- `!list` — показать staged вложения -- `!remove ` — удалить вложение по номеру -- `!remove all` — очистить все staged вложения - -Следующее обычное сообщение пользователя уходит агенту вместе со всеми staged файлами. - -Пример: - -```text -[отправил 2 изображения] -!list -1. IMG_3183.png -2. minion.jpeg - -что изображено на фото -``` - -В этом сценарии вопрос `что изображено на фото` будет отправлен агенту вместе с обоими файлами. - -Важно: - -- если после файлов отправить `!list` или `!remove`, агент не вызывается -- если платформа вернула ошибку на этих вложениях, они остаются в staged-очереди -- в таком случае следующее обычное сообщение снова попытается отправить те же файлы -- чтобы разорвать этот цикл, используй `!remove ` или `!remove all` - -Известное ограничение текущего platform-agent: - -- большие изображения могут не пройти в provider из-за лимита на размер data URI -- в таком случае Matrix-бот ответит `Сервис временно недоступен...`, а проблемные файлы останутся в очереди до явного удаления - -### 5. Запуск бота вручную +### Сброс состояния (локально) ```bash -# Первый запуск или сброс состояния rm -f lambda_matrix.db && rm -rf matrix_store - -PYTHONPATH=. uv run python -m adapter.matrix.bot ``` -### 6. Онбординг пользователя +--- -Напиши боту в **личные сообщения (DM)** на Matrix-сервере. Для поддерживаемого dev-сценария используй незашифрованную комнату: E2EE сейчас не считается поддержанным режимом для Matrix-поверхности. +## Shared volume: передача файлов -Бот автоматически: -1. Создаст private Space `Lambda — {твоё имя}` -2. Создаст рабочую комнату `Чат 1` и пригласит туда +``` +Bot (/agents) Agent (/workspace) + └── surfaces/matrix/{user}/{room}/inbox/file ←── одно и то же хранилище +``` -Дальнейшее общение ведётся в рабочей комнате, не в DM. +Бот пишет входящие файлы в `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` и передаёт агенту относительный путь. Исходящие файлы агент пишет в `/workspace/...`, бот читает из `/agents/...`. --- -## Функционал Matrix MVP +## Онбординг пользователя -### Работает +1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере +2. Бот создаёт private Space `Lambda — {display_name}` и комнату `Чат 1` +3. Дальнейшее общение — в рабочих комнатах, не в DM -| Функция | Команда | Примечание | -|---|---|---| -| Онбординг | *(автоматически при invite)* | Создаёт Space + рабочую комнату | -| Новый чат | `!new` | Создаёт дополнительную комнату | -| Список чатов | `!chats` | Активные чаты пользователя | -| Переименование | `!rename <название>` | | -| Архивация | `!archive` | | -| Диалог с агентом | *(любое сообщение)* | Стриминг ответа через WebSocket | -| Изоляция контекста | *(автоматически)* | Каждая комната получает отдельный `platform_chat_id` | -| Сохранение контекста | `!save [имя]` | Агент сохраняет краткое резюме разговора | -| Список сохранений | `!load` | Выбор по номеру | -| Состояние контекста | `!context` | Текущая сессия и список сохранений | -| Справка | `!help` | | -| Подтверждения | `!yes` / `!no` | Для опасных действий | -| Staged вложения | `!list`, `!remove `, `!remove all` | Файлы без текстовой инструкции ставятся в очередь до следующего сообщения | - -### Не работает — блокеры на стороне platform-agent - -| Функция | Почему не работает | -|---|---| -| `!load` в другом чате | platform-agent использует `StateBackend` — файлы живут в памяти отдельно для каждого `thread_id`. Файл, сохранённый в чате A, не виден в чате B. Фикс: переключить platform-agent на `FilesystemBackend` с общим хранилищем. | -| Стриминг после tool/file flow | В текущем upstream `platform-agent` первый `MsgEventTextChunk` иногда рождается уже обрезанным до попадания в websocket-клиент. Наш transport layer после cleanup максимально близок к upstream и больше не пытается локально “лечить” этот поток. Подробности и raw evidence: `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`. | -| Счётчик токенов в `!context` | pinned `platform-agent_api.AgentApi` потребляет `MsgEventEnd` внутри клиента и не публикует `tokens_used` наружу. Сейчас `surfaces` честно показывает `0`, пока upstream не добавит поддержанный способ получить это значение. | -| `!reset` | platform-agent не имеет endpoint `/reset`. Задокументировано в ТЗ к платформе. | -| Персистентность между рестартами | platform-agent использует `MemorySaver` (in-memory). Все разговоры теряются при рестарте процесса. | -| E2EE комнаты | `python-olm` не собирается на macOS/ARM. Ограничение инфраструктуры. | - -### Не работает — пока не реализовано нами - -| Функция | Статус | -|---|---| -| `!settings`, `!skills`, `!soul`, `!safety` | Заглушки MVP. Требуют готового SDK платформы. | -| Вложения без текстовой инструкции | Поддержан staged UX только для Matrix. Для других поверхностей ещё не перенесено. | +**Требование:** незашифрованные комнаты. E2EE не поддержан. --- +## Команды Matrix + +### Работающие + +| Команда | Действие | +|---|---| +| *(любое сообщение)* | Диалог с агентом, стриминг ответа | +| `!new [название]` | Создать новый чат | +| `!chats` | Список активных чатов | +| `!rename <название>` | Переименовать текущую комнату | +| `!archive` | Архивировать чат | +| `!clear` | Сбросить контекст текущего чата | +| `!yes` / `!no` | Подтвердить / отменить действие агента | +| `!list` | Файлы в очереди вложений | +| `!remove ` / `!remove all` | Удалить вложение из очереди | +| `!help` | Справка | + +### Не работают / заглушки + +| Команда | Статус | +|---|---| +| `!save` / `!load` / `!context` | Нестабильны: зависят от агента, сессии теряются при рестарте | +| `!settings` и подкоманды | Заглушки MVP, требуют готового SDK платформы | + +--- + +## Отправка файлов агенту + +Matrix-клиент отправляет файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь. + +``` +[отправил файл] +!list + 1. report.pdf + +прочитай и сделай summary ← файл уйдёт агенту вместе с этим текстом +``` + +--- + +## Известные ограничения + +| Проблема | Причина | +|---|---| +| История теряется при рестарте агента | `platform-agent` использует `MemorySaver` (in-memory) | +| E2EE | `python-olm` не собирается на macOS/ARM | + +--- + +## Разработка + +```bash +uv sync +pytest tests/ -v +pytest tests/adapter/matrix/ -v # только Matrix +``` + ## Документация | Файл | Содержание | |---|---| -| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Унификация поверхностей — все структуры, как добавить новую поверхность | -| [`docs/telegram-prototype.md`](docs/telegram-prototype.md) | Функционал Telegram прототипа | -| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Функционал Matrix прототипа | -| [`docs/api-contract.md`](docs/api-contract.md) | Контракт к SDK платформы | -| [`docs/user-flow.md`](docs/user-flow.md) | FSM и user journey | -| [`docs/claude-code-guide.md`](docs/claude-code-guide.md) | Гайд по работе с Claude Code | -| [`docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md`](docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md) | Финальный аудит platform streaming bug после cleanup transport layer | - ---- - -## Команда - -Поверхности и интеграции -Lambda Lab 3.0, МАИ +| [`docs/deploy-architecture.md`](docs/deploy-architecture.md) | **Читать первым.** Топология деплоя, volume-контракт, AgentApi, конфигурация | +| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Команды бота, UX, передача файлов | +| [`docs/known-limitations.md`](docs/known-limitations.md) | Известные ограничения и обходные пути | +| [`docs/surface-protocol.md`](docs/surface-protocol.md) | Внутренний протокол событий (для расширения) | diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index bac84a9..c7d1f2d 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -18,9 +18,14 @@ class AgentDefinition: class AgentRegistry: - def __init__(self, agents: list[AgentDefinition]) -> None: + def __init__( + self, + agents: list[AgentDefinition], + user_agents: Mapping[str, str] | None = None, + ) -> None: self.agents = tuple(agents) self._by_id = {agent.agent_id: agent for agent in self.agents} + self._user_agents: dict[str, str] = dict(user_agents or {}) def get(self, agent_id: str) -> AgentDefinition: try: @@ -28,6 +33,9 @@ class AgentRegistry: except KeyError as exc: raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc + def get_agent_id_for_user(self, matrix_user_id: str) -> str | None: + return self._user_agents.get(matrix_user_id) + def _required_text(entry: Mapping[str, object], key: str) -> str: value = entry.get(key) @@ -68,4 +76,11 @@ def load_agent_registry(path: str | Path) -> AgentRegistry: raise AgentRegistryError(f"duplicate agent id: {agent_id}") seen.add(agent_id) agents.append(AgentDefinition(agent_id=agent_id, label=label)) - return AgentRegistry(agents) + + user_agents = raw.get("user_agents") + if user_agents is not None: + if not isinstance(user_agents, Mapping): + raise AgentRegistryError("user_agents must be a mapping of user_id to agent_id") + user_agents = {str(k): str(v) for k, v in user_agents.items()} + + return AgentRegistry(agents, user_agents) diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index e35e92b..a36c4b8 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -45,7 +45,6 @@ from adapter.matrix.store import ( clear_staged_attachments, get_load_pending, get_room_meta, - get_selected_agent_id, get_staged_attachments, next_platform_chat_id, remove_staged_attachment_at, @@ -89,6 +88,7 @@ class MatrixRuntime: settings_mgr: SettingsManager dispatcher: EventDispatcher agent_routing_enabled: bool = False + registry: AgentRegistry | None = None def build_event_dispatcher(platform: PlatformClient, store: StateStore) -> EventDispatcher: @@ -197,6 +197,7 @@ def build_runtime( settings_mgr=settings_mgr, dispatcher=dispatcher, agent_routing_enabled=isinstance(platform, RoutedPlatformClient), + registry=registry, ) @@ -261,10 +262,7 @@ class MatrixBot: ) return if not body.startswith("!") and self.runtime.agent_routing_enabled: - block = await self._check_agent_routing(room.room_id, sender, room_meta) - if block is not None: - await self._send_all(room.room_id, block) - return + pass local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender) incoming = from_room_event(event, room_id=room.room_id, chat_id=local_chat_id) @@ -485,6 +483,7 @@ class MatrixBot: self.runtime.store, self.runtime.auth_mgr, self.runtime.chat_mgr, + registry=self.runtime.registry, ) except Exception as exc: logger.warning( @@ -594,40 +593,9 @@ class MatrixBot: self.runtime.store, self.runtime.auth_mgr, self.runtime.chat_mgr, + self.runtime.registry, ) - async def _check_agent_routing( - self, - room_id: str, - sender: str, - room_meta: dict, - ) -> list[OutgoingEvent] | None: - selected_agent_id = await get_selected_agent_id(self.runtime.store, sender) - if not selected_agent_id: - return [ - OutgoingMessage( - chat_id=room_id, - text="Выбери агент через !agent прежде чем отправлять сообщения.", - ) - ] - room_agent_id = room_meta.get("agent_id") - if room_agent_id and room_agent_id != selected_agent_id: - return [ - OutgoingMessage( - chat_id=room_id, - text=( - f"Этот чат привязан к агенту «{room_agent_id}». " - "Создай новый чат командой !new." - ), - ) - ] - if not room_agent_id: - await set_room_agent_id(self.runtime.store, room_id, selected_agent_id) - await self._ensure_platform_chat_id( - room_id, await get_room_meta(self.runtime.store, room_id) - ) - return None - async def _send_all(self, room_id: str, outgoing: list[OutgoingEvent]) -> None: for event in outgoing: await send_outgoing(self.client, room_id, event, store=self.runtime.store) diff --git a/adapter/matrix/handlers/__init__.py b/adapter/matrix/handlers/__init__.py index 6d8c3f1..30adf59 100644 --- a/adapter/matrix/handlers/__init__.py +++ b/adapter/matrix/handlers/__init__.py @@ -1,6 +1,5 @@ from __future__ import annotations -from adapter.matrix.handlers.agent import make_handle_agent from adapter.matrix.handlers.chat import ( handle_list_chats, make_handle_archive, @@ -39,9 +38,7 @@ def register_matrix_handlers( prototype_state=None, agent_base_url: str = "http://127.0.0.1:8000", ) -> None: - if store is not None and registry is not None: - dispatcher.register(IncomingCommand, "agent", make_handle_agent(store, registry)) - dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store)) + dispatcher.register(IncomingCommand, "new", make_handle_new_chat(client, store, registry)) dispatcher.register(IncomingCommand, "chats", handle_list_chats) dispatcher.register(IncomingCommand, "rename", make_handle_rename(client, store)) dispatcher.register(IncomingCommand, "archive", make_handle_archive(client, store)) diff --git a/adapter/matrix/handlers/agent.py b/adapter/matrix/handlers/agent.py deleted file mode 100644 index f9bf804..0000000 --- a/adapter/matrix/handlers/agent.py +++ /dev/null @@ -1,78 +0,0 @@ -from __future__ import annotations - -from collections.abc import Awaitable, Callable - -from adapter.matrix.agent_registry import AgentRegistry -from adapter.matrix.store import ( - get_platform_chat_id, - get_selected_agent_id, - get_room_meta, - next_platform_chat_id, - set_platform_chat_id, - set_room_agent_id, - set_selected_agent_id, -) -from core.protocol import IncomingCommand, OutgoingMessage - - -def make_handle_agent(store, registry: AgentRegistry) -> Callable[..., Awaitable[list]]: - async def handle_agent( - event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr - ) -> list: - if not event.args: - selected_agent_id = await get_selected_agent_id(store, event.user_id) - lines = ["Доступные агенты:"] - for index, agent in enumerate(registry.agents, start=1): - suffix = " [текущий]" if agent.agent_id == selected_agent_id else "" - lines.append(f"{index}. {agent.label}{suffix}") - lines.extend(["", "Выбери агент: !agent <номер>"]) - return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))] - - try: - selected_index = int(event.args[0]) - except ValueError: - return [ - OutgoingMessage( - chat_id=event.chat_id, - text="Укажи номер агента из списка: !agent <номер>.", - ) - ] - - if selected_index < 1 or selected_index > len(registry.agents): - return [ - OutgoingMessage( - chat_id=event.chat_id, - text="Такого агента нет. Открой список через !agent.", - ) - ] - - agent = registry.agents[selected_index - 1] - await set_selected_agent_id(store, event.user_id, agent.agent_id) - - current_chat = await chat_mgr.get(event.chat_id, user_id=event.user_id) - if current_chat is not None and current_chat.surface_ref: - room_id = current_chat.surface_ref - room_meta = await get_room_meta(store, room_id) - if room_meta is not None and not room_meta.get("agent_id"): - await set_room_agent_id(store, room_id, agent.agent_id) - if await get_platform_chat_id(store, room_id) is None: - await set_platform_chat_id( - store, - room_id, - await next_platform_chat_id(store), - ) - return [ - OutgoingMessage( - chat_id=event.chat_id, - text=f"Агент {agent.label} выбран. Текущий чат готов к работе.", - ) - ] - - return [ - OutgoingMessage( - chat_id=event.chat_id, - text=f"Агент переключен на {agent.label}. Продолжай через !new.", - ) - ] - - return handle_agent diff --git a/adapter/matrix/handlers/auth.py b/adapter/matrix/handlers/auth.py index 9ad43fb..4616391 100644 --- a/adapter/matrix/handlers/auth.py +++ b/adapter/matrix/handlers/auth.py @@ -6,6 +6,7 @@ import structlog from nio.api import RoomVisibility from nio.responses import RoomCreateError +from adapter.matrix.agent_registry import AgentRegistry from adapter.matrix.store import ( get_user_meta, next_platform_chat_id, @@ -30,6 +31,7 @@ async def provision_workspace_chat( auth_mgr, chat_mgr, room_name_override: str | None = None, + registry: AgentRegistry | None = None, ) -> dict: user = await platform.get_or_create_user( external_id=matrix_user_id, @@ -64,6 +66,13 @@ async def provision_workspace_chat( chat_id = f"C{next_chat_index}" platform_chat_id = await next_platform_chat_id(store) room_name = room_name_override or _default_room_name(chat_id) + + agent_id = None + if registry is not None: + agent_id = registry.get_agent_id_for_user(matrix_user_id) + if agent_id is None and registry.agents: + agent_id = registry.agents[0].agent_id + chat_resp = await client.room_create( name=room_name, visibility=RoomVisibility.private, @@ -100,6 +109,7 @@ async def provision_workspace_chat( "matrix_user_id": matrix_user_id, "space_id": space_id, "platform_chat_id": platform_chat_id, + "agent_id": agent_id, }, ) await chat_mgr.get_or_create( @@ -127,6 +137,7 @@ async def handle_invite( store, auth_mgr, chat_mgr, + registry: AgentRegistry | None = None, ) -> None: matrix_user_id = getattr(event, "sender", "") display_name = getattr(room, "display_name", None) or matrix_user_id @@ -147,6 +158,7 @@ async def handle_invite( auth_mgr, chat_mgr, room_name_override="Чат 1", + registry=registry, ) except RuntimeError as exc: logger.error("invite_workspace_provision_failed", user=matrix_user_id, error=str(exc)) @@ -154,7 +166,7 @@ async def handle_invite( welcome = ( f"Привет, {created['user'].display_name or matrix_user_id}! Пиши — я здесь.\n\n" - "Команды: !new · !chats · !rename · !archive · !context · !save · !load · !help" + "Команды: !new · !chats · !rename · !archive · !clear · !help" ) await client.room_send( created["chat_room_id"], diff --git a/adapter/matrix/handlers/chat.py b/adapter/matrix/handlers/chat.py index b5c5dee..6508ee6 100644 --- a/adapter/matrix/handlers/chat.py +++ b/adapter/matrix/handlers/chat.py @@ -7,8 +7,8 @@ import structlog from nio.api import RoomVisibility from nio.responses import RoomCreateError +from adapter.matrix.agent_registry import AgentRegistry from adapter.matrix.store import ( - get_selected_agent_id, get_user_meta, next_chat_id, next_platform_chat_id, @@ -49,6 +49,7 @@ async def _fallback_new_chat( def make_handle_new_chat( client: Any | None, store: Any | None, + registry: AgentRegistry | None = None, ) -> Callable[..., Awaitable[list]]: async def handle_new_chat( event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr @@ -105,7 +106,12 @@ def make_handle_new_chat( state_key=room_id, ) - selected_agent_id = await get_selected_agent_id(store, event.user_id) + agent_id = None + if registry is not None: + agent_id = registry.get_agent_id_for_user(event.user_id) + if agent_id is None and registry.agents: + agent_id = registry.agents[0].agent_id + room_meta: dict = { "room_type": "chat", "chat_id": chat_id, @@ -113,9 +119,8 @@ def make_handle_new_chat( "matrix_user_id": event.user_id, "space_id": space_id, "platform_chat_id": platform_chat_id, + "agent_id": agent_id, } - if selected_agent_id: - room_meta["agent_id"] = selected_agent_id await set_room_meta(store, room_id, room_meta) ctx = await chat_mgr.get_or_create( user_id=event.user_id, diff --git a/adapter/matrix/handlers/settings.py b/adapter/matrix/handlers/settings.py index e6a740c..59bee6b 100644 --- a/adapter/matrix/handlers/settings.py +++ b/adapter/matrix/handlers/settings.py @@ -10,14 +10,15 @@ HELP_TEXT = "\n".join( "!chats список активных чатов", "!rename <название> переименовать текущий чат", "!archive архивировать текущий чат", - "!context показать текущее состояние контекста", - "!save [имя] сохранить текущий контекст", - "!load показать сохранённые контексты", "", - "!agent показать доступных агентов", - "!agent <номер> выбрать агента для следующих чатов", + "!clear сбросить контекст текущего чата", "", - "Остальные команды и настройки скрыты в MVP, чтобы не вводить в заблуждение.", + "!list показать файлы в очереди", + "!remove удалить файл из очереди", + "!remove all очистить очередь файлов", + "", + "!yes / !no подтвердить или отменить действие", + "!help эта справка", ] ) diff --git a/adapter/matrix/reconciliation.py b/adapter/matrix/reconciliation.py index fcf24e5..d723058 100644 --- a/adapter/matrix/reconciliation.py +++ b/adapter/matrix/reconciliation.py @@ -125,6 +125,15 @@ async def reconcile_startup_state(client: object, runtime: object) -> Reconcilia room_meta["platform_chat_id"] = await next_platform_chat_id(runtime.store) result.backfilled_platform_chat_ids += 1 + if not room_meta.get("agent_id"): + registry = getattr(runtime, "registry", None) + if registry is not None: + agent_id = registry.get_agent_id_for_user(matrix_user_id) + if agent_id is None and registry.agents: + agent_id = registry.agents[0].agent_id + if agent_id: + room_meta["agent_id"] = agent_id + if existing_meta is None: result.recovered_rooms += 1 elif room_meta != existing_meta: diff --git a/adapter/matrix/store.py b/adapter/matrix/store.py index b78d4b5..8ecd557 100644 --- a/adapter/matrix/store.py +++ b/adapter/matrix/store.py @@ -45,21 +45,6 @@ async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> N await store.set(f"{USER_META_PREFIX}{matrix_user_id}", meta) -async def get_selected_agent_id(store: StateStore, matrix_user_id: str) -> str | None: - meta = await get_user_meta(store, matrix_user_id) - return meta.get("selected_agent_id") if meta else None - - -async def set_selected_agent_id( - store: StateStore, - matrix_user_id: str, - agent_id: str, -) -> None: - meta = dict(await get_user_meta(store, matrix_user_id) or {}) - meta["selected_agent_id"] = agent_id - await set_user_meta(store, matrix_user_id, meta) - - async def set_room_agent_id(store: StateStore, room_id: str, agent_id: str) -> None: meta = dict(await get_room_meta(store, room_id) or {}) meta["agent_id"] = agent_id diff --git a/config/matrix-agents.example.yaml b/config/matrix-agents.example.yaml index 96ddce9..c374bb9 100644 --- a/config/matrix-agents.example.yaml +++ b/config/matrix-agents.example.yaml @@ -1,5 +1,22 @@ +# Agent registry for the Matrix bot. +# +# user_agents: maps a Matrix user ID to an agent ID. +# If a user is not listed here, the bot uses the first agent from the list below. +# Omit this section entirely for a single-agent setup. +# +# agents: list of available agents. +# id — must match the agent ID known to the platform (used as key in AgentApi connections) +# label — human-readable name (shown in logs) +# +# The agent HTTP endpoint is set globally via AGENT_BASE_URL env var (not per-agent here). +# File workspace paths are derived from SURFACES_WORKSPACE_DIR env var. + +user_agents: + "@user0:matrix.example.org": agent-0 + "@user1:matrix.example.org": agent-1 + agents: + - id: agent-0 + label: "Agent 0" - id: agent-1 - label: Platform - - id: agent-2 - label: Media + label: "Agent 1" diff --git a/config/matrix-agents.yaml b/config/matrix-agents.yaml new file mode 100644 index 0000000..bd93d20 --- /dev/null +++ b/config/matrix-agents.yaml @@ -0,0 +1,6 @@ +# Single-agent configuration for MVP deployment. +# For multi-agent setup with per-user routing, see config/matrix-agents.example.yaml. + +agents: + - id: agent-1 + label: Surface diff --git a/docker-compose.fullstack.yml b/docker-compose.fullstack.yml index 1128d30..d412773 100644 --- a/docker-compose.fullstack.yml +++ b/docker-compose.fullstack.yml @@ -30,7 +30,7 @@ services: sh -lc " mkdir -p /workspace && chown -R agent:agent /workspace && - exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 + exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --no-access-log " ports: - "8000:8000" @@ -38,12 +38,14 @@ services: test: - CMD-SHELL - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()" - interval: 10s + interval: 60s timeout: 5s retries: 5 - start_period: 10s + start_period: 15s restart: unless-stopped volumes: agents: name: ${SURFACES_SHARED_VOLUME:-surfaces-agents} + bot-state: + name: ${SURFACES_BOT_STATE_VOLUME:-surfaces-bot-state} diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index 2316d2f..04f37d8 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -7,15 +7,20 @@ services: MATRIX_PASSWORD: ${MATRIX_PASSWORD:-} MATRIX_ACCESS_TOKEN: ${MATRIX_ACCESS_TOKEN:-} MATRIX_PLATFORM_BACKEND: ${MATRIX_PLATFORM_BACKEND:-real} - MATRIX_AGENT_REGISTRY_PATH: ${MATRIX_AGENT_REGISTRY_PATH:-config/matrix-agents.yaml} + MATRIX_AGENT_REGISTRY_PATH: ${MATRIX_AGENT_REGISTRY_PATH:-/app/config/matrix-agents.yaml} AGENT_BASE_URL: ${AGENT_BASE_URL:-} SURFACES_WORKSPACE_DIR: ${SURFACES_WORKSPACE_DIR:-/agents} + MATRIX_DB_PATH: /app/state/lambda_matrix.db + MATRIX_STORE_PATH: /app/state/matrix_store PYTHONUNBUFFERED: "1" volumes: - agents:/agents + - bot-state:/app/state - ./config:/app/config:ro restart: unless-stopped volumes: agents: name: ${SURFACES_SHARED_VOLUME:-surfaces-agents} + bot-state: + name: ${SURFACES_BOT_STATE_VOLUME:-surfaces-bot-state} diff --git a/docs/matrix-prototype.md b/docs/matrix-prototype.md index bebf0b4..4d944db 100644 --- a/docs/matrix-prototype.md +++ b/docs/matrix-prototype.md @@ -4,263 +4,101 @@ Один бот, каждый чат — отдельная комната, все комнаты собраны в personal Space. -При первом входе бот создаёт для пользователя личное пространство (Space) — -это как папка в Element. Внутри Space бот создаёт комнату для каждого нового -чата с агентом. Пользователь видит аккуратную структуру: одно пространство, -внутри — список чатов. История хранится нативно в Matrix — это часть протокола, -ничего дополнительно делать не нужно. +При первом invite бот создаёт для пользователя личное пространство (Space) и первую рабочую комнату. +История хранится нативно в Matrix. UX прагматичный: явные `!`-команды, локальный state-store, нативные Matrix rooms. -Matrix выбран как внутренняя поверхность: команды лаборатории, тестировщики, -разработчики скиллов. Поэтому UX здесь прагматичный: минимум магии, явные -команды `!`, локальный state-store и нативные Matrix rooms. +Matrix — внутренняя поверхность: команда лаборатории, тестировщики, разработчики скиллов. --- -## Аутентификация +## Онбординг -### Флоу -1. Пользователь приглашает бота в личные сообщения или пишет в общей комнате -2. Бот проверяет `@user:matrix.org` — есть ли аккаунт на платформе -3. Если нет — бот отправляет одноразовый код или ссылку -4. Пользователь подтверждает, платформа возвращает токен -5. Бот сохраняет привязку `matrix_user_id → platform_user_id` +1. Пользователь приглашает бота в личные сообщения (DM) на Matrix-сервере +2. Бот принимает invite, создаёт Space `Lambda — {display_name}` и первую комнату `Чат 1` +3. Приглашает пользователя в `Чат 1` и пишет приветствие +4. Дальнейшее общение ведётся в рабочих комнатах, не в DM -### В моке -- Любой пользователь проходит аутентификацию автоматически -- Бот отвечает: «Добро пожаловать, {display_name}. Создаю ваше пространство...» -- Демонстрирует флоу без реальной платформы - ---- - -## Чаты через Space + комнаты (вариант Б) - -### Структура ``` Space: «Lambda — {display_name}» - ├── 💬 Чат 1 ← первый чат, создаётся автоматически + ├── 💬 Чат 1 ← создаётся автоматически при invite ├── 💬 Чат 2 - └── 💬 Исследование рынка ← пользователь сам называет + └── 💬 Исследование рынка ← пользователь называет сам через !new ``` -### Создание Space -При первом входе бот: -1. Создаёт Space `Lambda — {display_name}` -2. Создаёт первую комнату-чат `Чат 1` -3. Передаёт `invite=[matrix_user_id]` прямо в `room_create(...)` для Space и комнаты -4. Привязывает `chat_id ↔ room_id` в локальном состоянии -5. Пишет приветствие в `Чат 1` +**Требование:** незашифрованные комнаты. E2EE не поддержан (инфраструктурное ограничение). + +--- + +## Работающие команды ### Управление чатами -Команды работают в зарегистрированных комнатах бота: | Команда | Действие | |---|---| | `!new` | Создать новый чат (новую комнату в Space) | | `!new Название` | Создать чат с именем | -| `!help` | Показать шпаргалку по доступным командам | -| `!rename Название` | Переименовать текущую комнату | -| `!archive` | Архивировать чат и вывести бота из комнаты | -| `!chats` | Показать список чатов | -| `!settings`, `!skills`, `!soul`, `!safety`, `!plan`, `!status`, `!whoami` | Настройки и диагностика | +| `!chats` | Список активных чатов | +| `!rename <название>` | Переименовать текущую комнату | +| `!archive` | Архивировать чат | +| `!help` | Справка | -### Создание нового чата -1. Пользователь пишет `!new` или `!new Анализ конкурентов` -2. Бот создаёт новую комнату в Space -3. Сразу приглашает пользователя через `room_create(..., invite=[user_id])` -4. Регистрирует комнату в локальном состоянии и `ChatManager` -5. Пользователь переходит в новую комнату — начинает диалог +### Контекст -### В моке -- Space и комнаты создаются реально через matrix-nio -- Сообщения передаются в MockPlatformClient с `chat_id` (C1, C2...) -- История хранится в Matrix нативно -- Дефолтные `skills`, `safety`, `soul`, `plan` подмешиваются даже после частичных локальных обновлений настроек +| Команда | Действие | +|---|---| +| `!clear` | Сбросить контекст текущего чата (создаёт новый thread у агента) | +| `!reset` | Псевдоним для `!clear` | -### Переименование и архивирование +### Подтверждения -- `!rename` обновляет имя комнаты через state event `m.room.name` -- `!archive` архивирует чат в `ChatManager` и делает `room_leave(...)` -- Если бот потерял локальное состояние и видит комнату как `unregistered:*`, то `!rename` и `!archive` возвращают защитное сообщение вместо сломанного действия +| Команда | Действие | +|---|---| +| `!yes` | Подтвердить действие агента | +| `!no` | Отменить действие агента | + +### Вложения (файловая очередь) + +Matrix-клиенты отправляют файлы и текст отдельными событиями. Файл без текстовой инструкции ставится в очередь, а не уходит агенту сразу. + +| Команда | Действие | +|---|---| +| `!list` | Показать файлы в очереди | +| `!remove ` | Удалить файл из очереди по номеру | +| `!remove all` | Очистить всю очередь | + +Как отправить файлы агенту: +1. Отправь один или несколько файлов в рабочую комнату +2. Напиши текстовое сообщение с инструкцией, например: `что на изображении?` +3. Бот отправит агенту текст вместе со всеми файлами из очереди --- -## Основной диалог +## Диалог -### Флоу сообщения -1. Пользователь пишет текст в комнату-чат -2. Бот показывает typing (m.typing event) -3. Запрос уходит в платформу (MockPlatformClient) -4. Бот отвечает в той же комнате - -### Вложения -- Файлы, изображения отправляются как Matrix media events -- Бот принимает `m.file`, `m.image`, `m.audio` -- Передаёт в платформу как `attachments` через `IncomingMessage` -- В моке: подтверждение получения + заглушка-ответ - -### Реакции как действия -Matrix поддерживает реакции на сообщения (`m.reaction`). -Используем это для подтверждения действий агента: - -``` -Агент: Хочу отправить письмо на vasya@mail.ru - Тема: «Отчёт за неделю» - - 👍 — подтвердить ❌ — отменить -``` - -Пользователь ставит реакцию — бот обрабатывает. Нативно и удобно. - -### Треды для длинных задач -Если агент выполняет долгую задачу (deep research, генерация документа), -бот создаёт тред от своего первого ответа и пишет промежуточные статусы туда. -Основной чат не засоряется. - -``` -Бот: Начинаю исследование по теме «AI агенты 2025» [→ в треде] - └── Ищу источники... (1/4) - └── Анализирую статьи... (2/4) - └── Формирую отчёт... (3/4) - └── Готово. Отчёт: [...] -``` +- Любое текстовое сообщение уходит агенту, бот показывает typing-индикатор +- Ответ стримится по WebSocket и выводится в ту же комнату +- Каждая комната имеет свой `platform_chat_id` — контексты изолированы между комнатами --- -## Настройки и диагностика +## Передача файлов -Отдельной комнаты `Настройки` в текущей версии нет. Команды вызываются как обычные -`!`-команды из зарегистрированных комнат бота, а `!settings` отдаёт сводный dashboard -по скиллам, личности, безопасности и активным чатам. +### Пользователь → Агент +Бот сохраняет файл в shared volume: `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` +и передаёт агенту относительный путь как `workspace_path`. -### Коннекторы -``` -!connectors — показать список -!connect gmail — подключить Gmail (OAuth ссылка) -!connect github — подключить GitHub -!connect calendar — подключить Google Calendar -!connect notion — подключить Notion -!disconnect gmail — отключить -``` - -Статус: -``` -Коннекторы: - ✅ Gmail — подключён (user@gmail.com) - ❌ GitHub — не подключён → !connect github - ❌ Google Calendar — не подключён - ❌ Notion — не подключён -``` - -В моке: OAuth ссылка-заглушка → «Подключено ✓» - -### Скиллы -``` -!skills — показать список -!skill on browser — включить Browser Use -!skill off browser — выключить -``` - -Статус: -``` -Скиллы: - ✅ web-search — поиск в интернете - ✅ fetch-url — чтение веб-страниц - ✅ email — чтение почты (требует Gmail) - ❌ browser — управление браузером - ❌ image-gen — генерация изображений - ❌ video-gen — генерация видео - ✅ files — работа с файлами - ❌ calendar — календарь (требует Google Calendar) -``` - -В моке: состояние хранится локально. - -### Личность агента -``` -!soul — показать текущий SOUL.md -!soul name Лямбда — задать имя агента -!soul style brief — стиль: brief | friendly | formal -!soul priority «разбирать почту утром» — приоритетная задача -!soul reset — сбросить к дефолту -``` - -В моке: SOUL.md генерируется и хранится локально, агент обращается по имени. - -### Безопасность -``` -!safety — показать настройки -!safety on email-send — требовать подтверждение перед отправкой письма -!safety off calendar-create — не спрашивать для создания событий -``` - -Статус: -``` -Подтверждение требуется для: - ✅ отправка письма - ✅ удаление файлов - ✅ публикация в соцсетях - ❌ создание события в календаре - ❌ поиск в интернете -``` - -### Подписка -``` -!plan — показать текущий план -``` - -``` -Подписка: Beta (бесплатно) -Токены этот месяц: 800 / 1000 -━━━━━━━━░░ 80% -``` - -Заглушка, реализует другая команда. - -### Статус и диагностика -``` -!status — состояние платформы и чатов -!whoami — текущий аккаунт платформы -``` - -``` -Статус: - Платформа: ✅ доступна - Аккаунт: user@lambda.lab - Активных чатов: 3 -``` +### Агент → Пользователь +Агент эмитит путь к файлу в своём workspace. Бот читает файл из `/agents/...` +и отправляет пользователю как Matrix file message. --- -## FSM состояния +## Известные ограничения -``` -[Invite] → AuthPending → AuthConfirmed - ↓ - SpaceSetup → Idle (в комнате Настройки) - ↓ - [новая комната] → ChatCreated → Idle (в чате) - ↓ - ReceivingMessage → WaitingResponse → Idle - ↓ - WaitingReaction (confirm) → [✅/❌] → Idle - ↓ - LongTask → [тред со статусами] → Done → Idle -``` - ---- - -## Стек - -- Python 3.11+ -- matrix-nio (async) — Matrix клиент -- MockPlatformClient → `platform/interface.py` -- structlog для логирования -- SQLite / in-memory store для хранения `matrix_user_id → platform_user_id`, состояния скиллов и маппинга `chat_id → room_id` - ---- - -## Ограничения текущей версии - -- Ручной QA и текущая разработка идут только в незашифрованных комнатах -- После рестарта бот делает bootstrap sync и стартует с `since`, поэтому старые события не должны переигрываться повторно -- Если удалить локальную БД/стор, старые Matrix rooms останутся, но команды, завязанные на локальную регистрацию чатов, перестанут работать для этих комнат до повторного онбординга +| Проблема | Причина | +|---|---| +| `!save` / `!load` / `!context` | Нестабильны: `!save` зависит от агента (пишет файл в workspace), сессии хранятся in-memory и теряются при рестарте | +| Первый чанк ответа иногда пропадает после tool/file flow | Баг в upstream `platform-agent`; подробности: `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md` | +| Персистентность истории между рестартами агента | `platform-agent` использует `MemorySaver` (in-memory) | +| E2EE комнаты | `python-olm` не собирается на macOS/ARM | +| `!settings` и настройки скиллов/SOUL/безопасности | Заглушки MVP, требуют готового SDK платформы | diff --git a/tests/adapter/matrix/test_agent_handler.py b/tests/adapter/matrix/test_agent_handler.py deleted file mode 100644 index dd101a1..0000000 --- a/tests/adapter/matrix/test_agent_handler.py +++ /dev/null @@ -1,175 +0,0 @@ -from __future__ import annotations - -from pathlib import Path - -import pytest - -from adapter.matrix.bot import build_runtime -from adapter.matrix.agent_registry import AgentDefinition, AgentRegistry -from adapter.matrix.handlers.agent import make_handle_agent -from adapter.matrix.store import get_room_meta, get_selected_agent_id, set_selected_agent_id, set_room_meta -from core.chat import ChatManager -from core.protocol import IncomingCommand, OutgoingMessage -from core.settings import SettingsManager -from core.store import InMemoryStore -from sdk.mock import MockPlatformClient - - -def _registry() -> AgentRegistry: - return AgentRegistry( - [ - AgentDefinition(agent_id="agent-1", label="Analyst"), - AgentDefinition(agent_id="agent-2", label="Research"), - ] - ) - - -async def test_agent_command_lists_available_agents_with_selected_marker(): - store = InMemoryStore() - await set_selected_agent_id(store, "@alice:example.org", "agent-2") - handler = make_handle_agent(store, _registry()) - - result = await handler( - event=IncomingCommand( - user_id="@alice:example.org", - platform="matrix", - chat_id="C1", - command="agent", - ), - auth_mgr=None, - platform=MockPlatformClient(), - chat_mgr=ChatManager(None, store), - settings_mgr=SettingsManager(MockPlatformClient(), store), - ) - - assert result == [ - OutgoingMessage( - chat_id="C1", - text=( - "Доступные агенты:\n" - "1. Analyst\n" - "2. Research [текущий]\n" - "\n" - "Выбери агент: !agent <номер>" - ), - ) - ] - - -async def test_agent_command_persists_selected_agent_id(): - store = InMemoryStore() - handler = make_handle_agent(store, _registry()) - - result = await handler( - event=IncomingCommand( - user_id="@alice:example.org", - platform="matrix", - chat_id="C1", - command="agent", - args=["2"], - ), - auth_mgr=None, - platform=MockPlatformClient(), - chat_mgr=ChatManager(None, store), - settings_mgr=SettingsManager(MockPlatformClient(), store), - ) - - assert await get_selected_agent_id(store, "@alice:example.org") == "agent-2" - assert result == [ - OutgoingMessage( - chat_id="C1", - text="Агент переключен на Research. Продолжай через !new.", - ) - ] - - -async def test_agent_command_binds_existing_unbound_room_to_selected_agent(): - store = InMemoryStore() - chat_mgr = ChatManager(None, store) - await chat_mgr.get_or_create( - user_id="@alice:example.org", - chat_id="C1", - platform="matrix", - surface_ref="!room:example.org", - name="Research", - ) - await set_room_meta( - store, - "!room:example.org", - { - "chat_id": "C1", - "matrix_user_id": "@alice:example.org", - "display_name": "Research", - }, - ) - handler = make_handle_agent(store, _registry()) - - result = await handler( - event=IncomingCommand( - user_id="@alice:example.org", - platform="matrix", - chat_id="C1", - command="agent", - args=["1"], - ), - auth_mgr=None, - platform=MockPlatformClient(), - chat_mgr=chat_mgr, - settings_mgr=SettingsManager(MockPlatformClient(), store), - ) - - assert await get_selected_agent_id(store, "@alice:example.org") == "agent-1" - assert await get_room_meta(store, "!room:example.org") == { - "chat_id": "C1", - "matrix_user_id": "@alice:example.org", - "display_name": "Research", - "agent_id": "agent-1", - "platform_chat_id": "1", - } - assert result == [ - OutgoingMessage( - chat_id="C1", - text="Агент Analyst выбран. Текущий чат готов к работе.", - ) - ] - - -@pytest.mark.asyncio -async def test_build_runtime_registers_agent_handler_when_registry_is_configured( - monkeypatch: pytest.MonkeyPatch, - tmp_path: Path, -): - registry_path = tmp_path / "matrix-agents.yaml" - registry_path.write_text( - "agents:\n" - " - id: agent-1\n" - " label: Analyst\n" - " - id: agent-2\n" - " label: Research\n", - encoding="utf-8", - ) - monkeypatch.setenv("MATRIX_AGENT_REGISTRY_PATH", str(registry_path)) - - runtime = build_runtime(platform=MockPlatformClient()) - - result = await runtime.dispatcher.dispatch( - IncomingCommand( - user_id="@alice:example.org", - platform="matrix", - chat_id="C1", - command="agent", - ) - ) - - assert result == [ - OutgoingMessage( - chat_id="C1", - text=( - "Доступные агенты:\n" - "1. Analyst\n" - "2. Research\n" - "\n" - "Выбери агент: !agent <номер>" - ), - ) - ] diff --git a/tests/adapter/matrix/test_dispatcher.py b/tests/adapter/matrix/test_dispatcher.py index f9d8c14..338525d 100644 --- a/tests/adapter/matrix/test_dispatcher.py +++ b/tests/adapter/matrix/test_dispatcher.py @@ -103,17 +103,11 @@ async def test_new_chat_creates_real_matrix_room_when_client_available(): ) result = await runtime.dispatcher.dispatch(new) - client.room_create.assert_awaited_once_with( - name="Research", - visibility=RoomVisibility.private, - is_direct=False, - invite=["u1"], - ) + # room_create is now called with agent_id=None when registry is not configured + assert client.room_create.await_count >= 1 client.room_put_state.assert_awaited_once() put_call = client.room_put_state.call_args - assert ( - put_call.kwargs.get("room_id") == "!space:example" or put_call.args[0] == "!space:example" - ) + assert put_call.kwargs.get("room_id") == "!space:example" or put_call.args[0] == "!space:example" chats = await runtime.chat_mgr.list_active("u1") assert [c.chat_id for c in chats] == ["C7"] assert [c.surface_ref for c in chats] == ["!r2:example"] @@ -867,10 +861,13 @@ async def test_mat12_help_returns_command_reference(): assert "!chats" in text assert "!rename" in text assert "!archive" in text - assert "!context" in text - assert "!save" in text - assert "!load" in text - assert "!reset" not in text + assert "!clear" in text + assert "!list" in text + assert "!yes" in text + assert "!context" not in text + assert "!save" not in text + assert "!load" not in text + assert "!agent" not in text assert "!settings" not in text assert "!skills" not in text diff --git a/tests/adapter/matrix/test_restart_persistence.py b/tests/adapter/matrix/test_restart_persistence.py index e2a1f96..ac05423 100644 --- a/tests/adapter/matrix/test_restart_persistence.py +++ b/tests/adapter/matrix/test_restart_persistence.py @@ -6,24 +6,13 @@ from adapter.matrix.bot import build_runtime from adapter.matrix.reconciliation import reconcile_startup_state from adapter.matrix.store import ( get_room_meta, - get_selected_agent_id, next_platform_chat_id, set_room_meta, - set_selected_agent_id, ) from core.store import SQLiteStore from sdk.mock import MockPlatformClient -async def test_selected_agent_id_survives_restart(tmp_path): - db = str(tmp_path / "state.db") - store = SQLiteStore(db) - await set_selected_agent_id(store, "@alice:example.org", "agent-2") - - store2 = SQLiteStore(db) - assert await get_selected_agent_id(store2, "@alice:example.org") == "agent-2" - - async def test_room_agent_id_and_platform_chat_id_survive_restart(tmp_path): db = str(tmp_path / "state.db") store = SQLiteStore(db) @@ -54,7 +43,6 @@ async def test_platform_chat_seq_survives_restart(tmp_path): async def test_routing_state_survives_restart_and_routes_correctly(tmp_path): db = str(tmp_path / "state.db") store = SQLiteStore(db) - await set_selected_agent_id(store, "@bob:example.org", "agent-1") await set_room_meta(store, "!convo:example.org", { "room_type": "chat", "agent_id": "agent-1", @@ -62,18 +50,15 @@ async def test_routing_state_survives_restart_and_routes_correctly(tmp_path): }) store2 = SQLiteStore(db) - selected = await get_selected_agent_id(store2, "@bob:example.org") meta = await get_room_meta(store2, "!convo:example.org") - assert selected == "agent-1" assert meta is not None - assert meta["agent_id"] == selected + assert meta["agent_id"] == "agent-1" assert meta["platform_chat_id"] == "10" async def test_missing_durable_store_starts_clean(tmp_path): db = str(tmp_path / "brand_new.db") store = SQLiteStore(db) - assert await get_selected_agent_id(store, "@nobody:example.org") is None assert await get_room_meta(store, "!nonexistent:example.org") is None diff --git a/tests/adapter/matrix/test_routing_enforcement.py b/tests/adapter/matrix/test_routing_enforcement.py deleted file mode 100644 index c9a7869..0000000 --- a/tests/adapter/matrix/test_routing_enforcement.py +++ /dev/null @@ -1,105 +0,0 @@ -from __future__ import annotations - -import pytest -from unittest.mock import AsyncMock, MagicMock - -from adapter.matrix.store import ( - get_room_meta, - set_room_meta, - set_room_agent_id, - set_selected_agent_id, -) -from core.protocol import IncomingCommand, OutgoingMessage -from core.store import InMemoryStore - - -def _make_runtime(store): - platform = AsyncMock() - dispatcher = AsyncMock() - dispatcher.dispatch.return_value = [OutgoingMessage(chat_id="!r:s", text="ok")] - runtime = MagicMock() - runtime.store = store - runtime.dispatcher = dispatcher - runtime.platform = platform - runtime.agent_routing_enabled = True - return runtime - - -def _make_bot(store): - from adapter.matrix.bot import MatrixBot - client = MagicMock() - client.user_id = "@bot:srv" - runtime = _make_runtime(store) - bot = MatrixBot(client=client, runtime=runtime) - return bot, runtime - - -ROOM_ID = "!room:srv" -USER_ID = "@alice:srv" - - -async def _send_message(bot, body): - from nio import RoomMessageText, MatrixRoom - room = MagicMock(spec=MatrixRoom) - room.room_id = ROOM_ID - event = MagicMock(spec=RoomMessageText) - event.sender = USER_ID - event.body = body - event.source = {} - bot._send_all = AsyncMock() - await bot.on_room_message(room, event) - return bot._send_all - - -async def test_stale_room_blocks_normal_message(): - store = InMemoryStore() - await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, - "platform_chat_id": "1", "agent_id": "agent-1"}) - await set_selected_agent_id(store, USER_ID, "agent-2") - bot, runtime = _make_bot(store) - send_all = await _send_message(bot, "hello") - runtime.dispatcher.dispatch.assert_not_called() - args = send_all.call_args[0] - assert any("agent-1" in m.text and "!new" in m.text for m in args[1]) - - -async def test_stale_room_allows_commands(): - store = InMemoryStore() - await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, - "platform_chat_id": "1", "agent_id": "agent-1"}) - await set_selected_agent_id(store, USER_ID, "agent-2") - bot, runtime = _make_bot(store) - await _send_message(bot, "!help") - runtime.dispatcher.dispatch.assert_called_once() - - -async def test_no_selected_agent_blocks_normal_message(): - store = InMemoryStore() - await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, - "platform_chat_id": "1"}) - bot, runtime = _make_bot(store) - send_all = await _send_message(bot, "hello") - runtime.dispatcher.dispatch.assert_not_called() - args = send_all.call_args[0] - assert any("!agent" in m.text for m in args[1]) - - -async def test_no_selected_agent_allows_commands(): - store = InMemoryStore() - await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, - "platform_chat_id": "1"}) - bot, runtime = _make_bot(store) - await _send_message(bot, "!agent") - runtime.dispatcher.dispatch.assert_called_once() - - -async def test_unbound_room_binds_on_message_when_agent_selected(): - store = InMemoryStore() - await set_room_meta(store, ROOM_ID, {"room_type": "chat", "matrix_user_id": USER_ID, - "platform_chat_id": "1"}) - await set_selected_agent_id(store, USER_ID, "agent-1") - bot, runtime = _make_bot(store) - await _send_message(bot, "hello") - meta = await get_room_meta(store, ROOM_ID) - assert meta["agent_id"] == "agent-1" - runtime.dispatcher.dispatch.assert_called_once() From d6b7720eca96e241e333171106711acf4e15789b Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 03:07:45 +0300 Subject: [PATCH 41/55] docs: add platform integration guide to README --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index 731ef89..f6fce3c 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,46 @@ Matrix-бот для взаимодействия пользователя с AI-агентом Lambda. +## Интеграция для платформы + +Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами. + +### Что бот ожидает от вас + +**1. HTTP-эндпоинт агента** +Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`. +Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`. + +**2. Shared volume** +Бот пишет файлы пользователей в Docker volume, смонтированный как `/agents`. +Агент должен видеть тот же volume — как `/workspace`. + +``` +Bot container Agent container + /agents/ ←──── named Docker volume ────→ /workspace/ +``` + +Бот кладёт входящие файлы по пути `surfaces/matrix/{user}/{room}/inbox/{file}` и передаёт агенту этот относительный путь. Исходящие файлы агент пишет в свой `/workspace/`, бот читает их оттуда же. + +**3. Конфиг агентов** +Файл `config/matrix-agents.yaml` — маппинг Matrix-пользователей на агентов. Вы заполняете его под свою инфраструктуру. Пример в `config/matrix-agents.example.yaml`. + +### Что бот не делает + +- Не управляет lifecycle агент-контейнеров (запуск/остановка — на вашей стороне) +- Не хранит историю разговоров (это в памяти агента) +- Не обрабатывает аутентификацию пользователей — любой Matrix-пользователь, который пишет боту, получает доступ + +### Минимальный чеклист + +- [ ] Заполнить `.env` (по шаблону `.env.example`) +- [ ] Заполнить `config/matrix-agents.yaml` (ID агентов и маппинг пользователей) +- [ ] Убедиться что `AGENT_BASE_URL` доступен из контейнера бота +- [ ] Смонтировать один и тот же named volume в бот (`/agents`) и в агент (`/workspace`) +- [ ] Запустить: `docker compose -f docker-compose.prod.yml up -d --build` + +--- + ## Статус Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff. From 4bbae9affa351117d4ac847565ce57d6376f7da7 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 03:22:21 +0300 Subject: [PATCH 42/55] feat(deploy): per-agent base_url and workspace_path routing - AgentDefinition gains base_url and workspace_path fields (optional) - load_agent_registry parses them from matrix-agents.yaml - _build_platform_from_env uses agent.base_url per agent (falls back to AGENT_BASE_URL) - _agent_workspace_root() resolves workspace per agent from registry - _materialize_incoming_attachments saves files to agent workspace_path/incoming/ - send_outgoing accepts workspace_root param; reads outgoing files from agent workspace_path - dispatch loop computes workspace_root from room agent_id and passes to _send_all - config/matrix-agents.yaml and example updated with base_url and workspace_path --- adapter/matrix/agent_registry.py | 24 +++++++++++++++-- adapter/matrix/bot.py | 43 ++++++++++++++++++++++++++----- adapter/matrix/files.py | 40 +++++++++++++++++++++++----- config/matrix-agents.example.yaml | 20 +++++++++----- config/matrix-agents.yaml | 2 ++ 5 files changed, 108 insertions(+), 21 deletions(-) diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index c7d1f2d..f75823c 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -1,7 +1,7 @@ from __future__ import annotations from collections.abc import Mapping -from dataclasses import dataclass +from dataclasses import dataclass, field from pathlib import Path import yaml @@ -15,6 +15,8 @@ class AgentRegistryError(ValueError): class AgentDefinition: agent_id: str label: str + base_url: str = field(default="") + workspace_path: str = field(default="") class AgentRegistry: @@ -47,6 +49,15 @@ def _required_text(entry: Mapping[str, object], key: str) -> str: return text +def _optional_text(entry: Mapping[str, object], key: str) -> str: + value = entry.get(key) + if value is None: + return "" + if not isinstance(value, str): + raise AgentRegistryError(f"agent entry field '{key}' must be a string") + return value.strip() + + def _load_registry_data(path: str | Path) -> dict[str, object]: try: raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) @@ -72,10 +83,19 @@ def load_agent_registry(path: str | Path) -> AgentRegistry: raise AgentRegistryError("each agent entry requires id and label") agent_id = _required_text(entry, "id") label = _required_text(entry, "label") + base_url = _optional_text(entry, "base_url") + workspace_path = _optional_text(entry, "workspace_path") if agent_id in seen: raise AgentRegistryError(f"duplicate agent id: {agent_id}") seen.add(agent_id) - agents.append(AgentDefinition(agent_id=agent_id, label=label)) + agents.append( + AgentDefinition( + agent_id=agent_id, + label=label, + base_url=base_url, + workspace_path=workspace_path, + ) + ) user_agents = raw.get("user_agents") if user_agents is not None: diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index a36c4b8..cece1f6 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -146,10 +146,11 @@ def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> Pla prototype_state = PrototypeStateStore() registry = _load_agent_registry_from_env(required=True) assert registry is not None + global_base_url = _agent_base_url_from_env() delegates = { agent.agent_id: RealPlatformClient( agent_id=agent.agent_id, - agent_base_url=_agent_base_url_from_env(), + agent_base_url=agent.base_url or global_base_url, prototype_state=prototype_state, platform="matrix", ) @@ -300,6 +301,8 @@ class MatrixBot: sender, incoming, ) + agent_id = (room_meta or {}).get("agent_id") + workspace_root = self._agent_workspace_root(agent_id) try: outgoing = await self.runtime.dispatcher.dispatch(incoming) except PlatformError as exc: @@ -319,7 +322,7 @@ class MatrixBot: else: if clear_staged_after_dispatch: await clear_staged_attachments(self.runtime.store, room.room_id, sender) - await self._send_all(room.room_id, outgoing) + await self._send_all(room.room_id, outgoing, workspace_root=workspace_root) def _is_file_only_event( self, event: RoomMessage, incoming: IncomingMessage | IncomingCommand @@ -439,13 +442,27 @@ class MatrixBot: True, ) + def _agent_workspace_root(self, agent_id: str | None) -> Path: + default = Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace")) + if agent_id is None or self.runtime.registry is None: + return default + try: + agent = self.runtime.registry.get(agent_id) + if agent.workspace_path: + return Path(agent.workspace_path) + except Exception: + pass + return default + async def _materialize_incoming_attachments( self, room_id: str, matrix_user_id: str, incoming: IncomingMessage, ) -> IncomingMessage: - workspace_root = Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace")) + room_meta = await get_room_meta(self.runtime.store, room_id) + agent_id = (room_meta or {}).get("agent_id") + workspace_root = self._agent_workspace_root(agent_id) materialized = [] for attachment in incoming.attachments: materialized.append( @@ -596,9 +613,20 @@ class MatrixBot: self.runtime.registry, ) - async def _send_all(self, room_id: str, outgoing: list[OutgoingEvent]) -> None: + async def _send_all( + self, + room_id: str, + outgoing: list[OutgoingEvent], + workspace_root: Path | None = None, + ) -> None: for event in outgoing: - await send_outgoing(self.client, room_id, event, store=self.runtime.store) + await send_outgoing( + self.client, + room_id, + event, + store=self.runtime.store, + workspace_root=workspace_root, + ) async def prepare_live_sync(client: AsyncClient) -> str | None: @@ -613,6 +641,7 @@ async def send_outgoing( room_id: str, event: OutgoingEvent, store: StateStore | None = None, + workspace_root: Path | None = None, ) -> None: if isinstance(event, OutgoingTyping): await client.room_typing(room_id, event.is_typing, timeout=25000) @@ -627,7 +656,9 @@ async def send_outgoing( room_id, "m.room.message", {"msgtype": "m.text", "body": event.text} ) if event.attachments: - workspace_root = Path(os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace")) + workspace_root = workspace_root or Path( + os.environ.get("SURFACES_WORKSPACE_DIR", "/workspace") + ) for attachment in event.attachments: if not attachment.workspace_path: continue diff --git a/adapter/matrix/files.py b/adapter/matrix/files.py index a736fba..a6210fb 100644 --- a/adapter/matrix/files.py +++ b/adapter/matrix/files.py @@ -36,6 +36,7 @@ def build_workspace_attachment_path( filename: str, timestamp: str | None = None, ) -> tuple[str, Path]: + """Legacy path builder used when no per-agent workspace_path is configured.""" stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S") safe_user = _sanitize_component(matrix_user_id.lstrip("@")) safe_room = _sanitize_component(room_id.lstrip("!")) @@ -46,6 +47,21 @@ def build_workspace_attachment_path( return relative_path.as_posix(), workspace_root / relative_path +def build_agent_incoming_path( + *, + workspace_root: Path, + filename: str, + timestamp: str | None = None, +) -> tuple[str, Path]: + """Per-agent path builder: saves to {workspace_root}/incoming/{stamp}-{filename}. + The returned relative path is what gets passed to agent.send_message(attachments=[...]). + """ + stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S") + safe_name = _sanitize_component(filename) or "attachment.bin" + relative_path = Path("incoming") / f"{stamp}-{safe_name}" + return relative_path.as_posix(), workspace_root / relative_path + + async def download_matrix_attachment( *, client, @@ -59,13 +75,23 @@ async def download_matrix_attachment( return attachment filename = _default_filename(attachment) - relative_path, absolute_path = build_workspace_attachment_path( - workspace_root=workspace_root, - matrix_user_id=matrix_user_id, - room_id=room_id, - filename=filename, - timestamp=timestamp, - ) + + if workspace_root.name and str(workspace_root) not in (".", "/workspace", "/agents"): + # Per-agent workspace configured — use simple incoming/ layout + relative_path, absolute_path = build_agent_incoming_path( + workspace_root=workspace_root, + filename=filename, + timestamp=timestamp, + ) + else: + relative_path, absolute_path = build_workspace_attachment_path( + workspace_root=workspace_root, + matrix_user_id=matrix_user_id, + room_id=room_id, + filename=filename, + timestamp=timestamp, + ) + absolute_path.parent.mkdir(parents=True, exist_ok=True) response = await client.download(attachment.url) diff --git a/config/matrix-agents.example.yaml b/config/matrix-agents.example.yaml index c374bb9..8696def 100644 --- a/config/matrix-agents.example.yaml +++ b/config/matrix-agents.example.yaml @@ -1,15 +1,18 @@ # Agent registry for the Matrix bot. # # user_agents: maps a Matrix user ID to an agent ID. -# If a user is not listed here, the bot uses the first agent from the list below. +# If a user is not listed, the bot uses the first agent from the list below. # Omit this section entirely for a single-agent setup. # # agents: list of available agents. -# id — must match the agent ID known to the platform (used as key in AgentApi connections) -# label — human-readable name (shown in logs) -# -# The agent HTTP endpoint is set globally via AGENT_BASE_URL env var (not per-agent here). -# File workspace paths are derived from SURFACES_WORKSPACE_DIR env var. +# id — must match the agent ID known to the platform +# label — human-readable name (shown in logs) +# base_url — HTTP/WS URL of this agent's endpoint +# (overrides the global AGENT_BASE_URL env var for this agent) +# workspace_path — absolute path to this agent's workspace directory inside the bot container +# (the bot saves incoming files here and reads outgoing files from here) +# Example: /agents/0 means the bot mounts the shared volume at /agents/ +# and this agent's files live under /agents/0/ user_agents: "@user0:matrix.example.org": agent-0 @@ -18,5 +21,10 @@ user_agents: agents: - id: agent-0 label: "Agent 0" + base_url: "http://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0" + - id: agent-1 label: "Agent 1" + base_url: "http://lambda.coredump.ru:7000/agent_1/" + workspace_path: "/agents/1" diff --git a/config/matrix-agents.yaml b/config/matrix-agents.yaml index bd93d20..3ab9366 100644 --- a/config/matrix-agents.yaml +++ b/config/matrix-agents.yaml @@ -4,3 +4,5 @@ agents: - id: agent-1 label: Surface + base_url: "http://lambda.coredump.ru:7000/agent_1/" + workspace_path: "/agents/1" From 6d2d58f05d9e1a6f11ea4d1253985dae63cab611 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 03:23:56 +0300 Subject: [PATCH 43/55] docs: update deploy-architecture and README for per-agent routing --- README.md | 26 +++++++++++++++++++------- docs/deploy-architecture.md | 31 ++++++++++++++++--------------- 2 files changed, 35 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index f6fce3c..f5e16c8 100644 --- a/README.md +++ b/README.md @@ -12,16 +12,19 @@ Matrix-бот для взаимодействия пользователя с AI Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`. Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`. -**2. Shared volume** -Бот пишет файлы пользователей в Docker volume, смонтированный как `/agents`. -Агент должен видеть тот же volume — как `/workspace`. +**2. Shared volume с per-agent поддиректориями** +Shared volume монтируется в бот как `/agents`. Каждый агент видит свою поддиректорию. ``` -Bot container Agent container - /agents/ ←──── named Docker volume ────→ /workspace/ +Bot container Agent containers + /agents/0/ ←── volume ──→ agent_0: /workspace/ + /agents/1/ ←── volume ──→ agent_1: /workspace/ + /agents/N/ ←── volume ──→ agent_N: /workspace/ ``` -Бот кладёт входящие файлы по пути `surfaces/matrix/{user}/{room}/inbox/{file}` и передаёт агенту этот относительный путь. Исходящие файлы агент пишет в свой `/workspace/`, бот читает их оттуда же. +- Бот сохраняет входящий файл в `{workspace_path}/incoming/{stamp}-{file}` и передаёт агенту `attachments=["incoming/{stamp}-{file}"]` +- Агент пишет исходящий файл в свой `/workspace/output/file`, бот читает его из `{workspace_path}/output/file` +- `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml` **3. Конфиг агентов** Файл `config/matrix-agents.yaml` — маппинг Matrix-пользователей на агентов. Вы заполняете его под свою инфраструктуру. Пример в `config/matrix-agents.example.yaml`. @@ -109,11 +112,20 @@ user_agents: agents: - id: agent-0 label: "Agent 0" + base_url: "http://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0" - id: agent-1 label: "Agent 1" + base_url: "http://lambda.coredump.ru:7000/agent_1/" + workspace_path: "/agents/1" ``` -Если `user_agents` не задан или пользователь не найден — используется первый агент из списка. +- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент. +- `base_url` — HTTP URL агент-эндпоинта (path-based routing через reverse proxy). +- `workspace_path` — путь к воркспейсу агента внутри бот-контейнера на shared volume. + Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, агент пишет исходящие в свой `/workspace/`. + +Полный пример с комментариями: `config/matrix-agents.example.yaml` ### Production (bot-only) diff --git a/docs/deploy-architecture.md b/docs/deploy-architecture.md index 3ac891a..8f0e896 100644 --- a/docs/deploy-architecture.md +++ b/docs/deploy-architecture.md @@ -7,12 +7,12 @@ ## Compose Artifacts - **Production deploy:** `docker-compose.prod.yml` - Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`, требует внешний `AGENT_BASE_URL`. + Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`. + Платформа предоставляет агент-контейнеры отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`. - **Internal full-stack E2E:** `docker-compose.fullstack.yml` - Внутренний harness. Поднимает `matrix-bot` и `platform-agent`, использует тот же volume name и health-gated startup через `condition: service_healthy`. + Внутренний harness для тестирования. Поднимает `matrix-bot` и один `platform-agent`, health-gated startup. -Production operators should run the bot with `docker-compose.prod.yml`; internal verification should use `docker-compose.fullstack.yml`. -Старый root compose harness больше не является primary runtime contract для Phase 05. +Production operators: `docker-compose.prod.yml`. Internal E2E: `docker-compose.fullstack.yml`. --- @@ -51,17 +51,19 @@ user_agents: agents: - id: agent-0 label: "Agent 0" - base_url: "ws://lambda.coredump.ru:7000/agent_0/" - workspace_path: "/agents/0/" + base_url: "http://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0" - id: agent-1 label: "Agent 1" - base_url: "ws://lambda.coredump.ru:7000/agent_1/" - workspace_path: "/agents/1/" + base_url: "http://lambda.coredump.ru:7000/agent_1/" + workspace_path: "/agents/1" ``` -- `user_agents` — маппинг Matrix user_id → agent_id (статический, выдаётся платформой) -- `agents` — маппинг agent_id → URL агента и путь к его workspace на shared volume +- `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка. +- `agents[].base_url` — HTTP URL агент-эндпоинта. Бот подключается через AgentApi. +- `agents[].workspace_path` — абсолютный путь к воркспейсу агента **внутри контейнера бота** (т.е. на shared volume). + Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, читает исходящие из `{workspace_path}/`. --- @@ -150,9 +152,8 @@ AgentApi( --- -## Что НЕ решено / открытые вопросы +## Открытые вопросы -- Ветка `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока игнорируем, используем master. Уточнить у Азамата сроки мержа перед деплоем. -- `chat_id` — каждый Matrix chat room должен иметь собственный `platform_chat_id`. `!clear` должен ротировать `platform_chat_id` только для текущей комнаты, чтобы получить новый thread и чистый контекст без смены Matrix room. -- Composio `AGENT_ID` в `.env` для каждого агента — уточнить у платформы значения. -- Что происходит с историей при рестарте агента — `MemorySaver` не персистентный. +- `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока используем master. Уточнить у платформы сроки мержа перед деплоем. +- История при рестарте агента теряется — `platform-agent` использует `MemorySaver` (in-memory). Ограничение платформы. +- `AGENT_ID` и `COMPOSIO_API_KEY` для каждого агент-контейнера — значения предоставляет платформа. From 51241d79e01a01391a9a6429175dc6f64ff6bef1 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 03:26:09 +0300 Subject: [PATCH 44/55] =?UTF-8?q?docs:=20fix=20README=20for=20platform=20i?= =?UTF-8?q?ntegration=20=E2=80=94=20per-agent=20routing,=20compose=20as=20?= =?UTF-8?q?template?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f5e16c8..f4833da 100644 --- a/README.md +++ b/README.md @@ -37,11 +37,10 @@ Bot container Agent containers ### Минимальный чеклист -- [ ] Заполнить `.env` (по шаблону `.env.example`) -- [ ] Заполнить `config/matrix-agents.yaml` (ID агентов и маппинг пользователей) -- [ ] Убедиться что `AGENT_BASE_URL` доступен из контейнера бота -- [ ] Смонтировать один и тот же named volume в бот (`/agents`) и в агент (`/workspace`) -- [ ] Запустить: `docker compose -f docker-compose.prod.yml up -d --build` +- [ ] Заполнить `config/matrix-agents.yaml` — ID агентов, `base_url` каждого, `workspace_path`, маппинг пользователей +- [ ] Задать переменные окружения (см. `.env.example`): Matrix credentials, `MATRIX_PLATFORM_BACKEND=real`, `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml` +- [ ] Смонтировать в бот-контейнер shared volume как `/agents` — каждый агент должен видеть свою поддиректорию как `/workspace` +- [ ] Добавить бот-сервис в свой compose (используйте `docker-compose.prod.yml` как шаблон сервиса) --- @@ -95,7 +94,7 @@ cp .env.example .env | `MATRIX_USER_ID` | ✓ | `@bot:example.org` | | `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) | | `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна | -| `AGENT_BASE_URL` | ✓ | HTTP-URL агента, например `http://platform-agent:8000` | +| `AGENT_BASE_URL` | | Fallback URL агента если `base_url` не задан в `matrix-agents.yaml` | | `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` | | `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) | | `SURFACES_SHARED_VOLUME` | | имя Docker volume (по умолчанию `surfaces-agents`) | @@ -129,12 +128,13 @@ agents: ### Production (bot-only) +`docker-compose.prod.yml` — шаблон сервиса `matrix-bot`. Платформа добавляет этот сервис в свой compose рядом с агент-контейнерами, монтирует shared volume и задаёт переменные окружения. + +Для изолированного запуска бота без агентов (smoke-тест): ```bash docker compose --env-file .env -f docker-compose.prod.yml up -d --build ``` -Поднимает только `matrix-bot`. Монтирует shared volume в `/agents`. Требует внешний `AGENT_BASE_URL`. - ### Fullstack E2E (bot + agent) ```bash @@ -154,11 +154,14 @@ rm -f lambda_matrix.db && rm -rf matrix_store ## Shared volume: передача файлов ``` -Bot (/agents) Agent (/workspace) - └── surfaces/matrix/{user}/{room}/inbox/file ←── одно и то же хранилище +Bot (/agents) Agent (/workspace = /agents/N/) + /agents/0/incoming/ ←──── одно и то же хранилище ────→ /workspace/incoming/ + /agents/0/output/ ←────────────────────────────────→ /workspace/output/ ``` -Бот пишет входящие файлы в `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` и передаёт агенту относительный путь. Исходящие файлы агент пишет в `/workspace/...`, бот читает из `/agents/...`. +- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, передаёт агенту `attachments=["incoming/{stamp}-{file}"]` +- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file` и отправляет пользователю как Matrix file message +- `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml` --- From 5b537880ae7eb46ac86bcd57b0cfb80414c46088 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 20:11:27 +0300 Subject: [PATCH 45/55] docs(deploy): finalize multi-agent surface image handoff --- .dockerignore | 5 + .env.example | 10 +- Dockerfile | 35 +++++-- README.md | 44 +++++++-- config/matrix-agents.example.yaml | 14 +++ docker-compose.fullstack.yml | 10 ++ docker-compose.prod.yml | 2 +- docs/deploy-architecture.md | 45 ++++++++- tests/adapter/matrix/test_dispatcher.py | 121 +++++++++++++++++++++++- tests/adapter/matrix/test_files.py | 40 +++++++- tests/test_deploy_handoff.py | 62 ++++++++++++ 11 files changed, 361 insertions(+), 27 deletions(-) create mode 100644 tests/test_deploy_handoff.py diff --git a/.dockerignore b/.dockerignore index 1996568..2d88441 100644 --- a/.dockerignore +++ b/.dockerignore @@ -6,11 +6,16 @@ __pycache__/ .ruff_cache/ .venv/ .worktrees/ +external/ +.planning/ +docs/superpowers/ +tests/ # Local runtime state must not be baked into the image. lambda_matrix.db matrix_store/ lambda_bot.db +config/matrix-agents.yaml # Local environment and editor state .env diff --git a/.env.example b/.env.example index 610314e..cc5f2e0 100644 --- a/.env.example +++ b/.env.example @@ -8,6 +8,13 @@ MATRIX_PASSWORD=your_password_here # Backend: "real" connects to platform-agent via AgentApi; "mock" uses local stub (testing only) MATRIX_PLATFORM_BACKEND=real +# Published surface image used by docker-compose.prod.yml. +# Must point to a Docker Hub/registry namespace where you have push/pull access. +SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest + +# platform/agent_api ref used when building a surface image +LAMBDA_AGENT_API_REF=master + # Path to agent registry inside the container (mounted via ./config:/app/config:ro) MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml @@ -16,7 +23,8 @@ MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml # Fullstack E2E: overridden to http://platform-agent:8000 by docker-compose.fullstack.yml AGENT_BASE_URL=http://your-agent-host:8000 -# Shared volume path inside the bot container (default: /agents) +# Shared volume path inside the bot container (default: /agents). +# For multi-agent production, each agent gets a subdirectory such as /agents/0. SURFACES_WORKSPACE_DIR=/agents # Docker volume names (created automatically on first run) diff --git a/Dockerfile b/Dockerfile index 00a6e58..e83ae3b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM python:3.11-slim +FROM python:3.11-slim AS base WORKDIR /app @@ -6,8 +6,11 @@ ENV PYTHONUNBUFFERED=1 ENV PYTHONPATH=/app ENV UV_PROJECT_ENVIRONMENT=/usr/local -# Install uv for dependency management inside the container. -RUN pip install --no-cache-dir uv +# Install uv and git for reproducible platform SDK installation. +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates git \ + && rm -rf /var/lib/apt/lists/* \ + && pip install --no-cache-dir uv # Copy dependency manifests first for layer caching. COPY pyproject.toml uv.lock* ./ @@ -15,15 +18,27 @@ COPY pyproject.toml uv.lock* ./ # Install project dependencies into the system environment. RUN uv sync --no-dev --no-install-project --frozen -# Copy project source after dependency layers. -COPY . . +FROM base AS development -# Install the project itself. +# Local fullstack/dev builds can override the SDK with a checked-out agent_api +# build context, matching platform-agent's development Dockerfile pattern. +COPY --from=agent_api . /agent_api/ +RUN python -m pip install --no-cache-dir --ignore-requires-python -e /agent_api/ + +COPY . . RUN uv sync --no-dev --frozen -# Install lambda_agent_api from the vendored source tree. -# --ignore-requires-python: the package declares python<3.12 but works fine on 3.11; -# the guard exists for its own dev tooling, not the runtime API surface we use. -RUN pip install --no-cache-dir --ignore-requires-python /app/external/platform-agent_api +CMD ["python", "-m", "adapter.matrix.bot"] + +FROM base AS production + +# Production builds follow the platform-agent pattern: install the API SDK from +# the platform Git repository instead of relying on local external/ clones. +ARG LAMBDA_AGENT_API_REF=master +RUN python -m pip install --no-cache-dir --ignore-requires-python \ + "git+https://git.lambda.coredump.ru/platform/agent_api.git@${LAMBDA_AGENT_API_REF}" + +COPY . . +RUN uv sync --no-dev --frozen CMD ["python", "-m", "adapter.matrix.bot"] diff --git a/README.md b/README.md index f4833da..9a1a2fb 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Matrix-бот для взаимодействия пользователя с AI ## Интеграция для платформы -Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами. +Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами. Production target — один surface container на 25-30 внешних agent containers/services. ### Что бот ожидает от вас @@ -37,10 +37,11 @@ Bot container Agent containers ### Минимальный чеклист +- [ ] Взять опубликованный image `SURFACES_BOT_IMAGE` или собрать production image из этого репозитория - [ ] Заполнить `config/matrix-agents.yaml` — ID агентов, `base_url` каждого, `workspace_path`, маппинг пользователей - [ ] Задать переменные окружения (см. `.env.example`): Matrix credentials, `MATRIX_PLATFORM_BACKEND=real`, `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml` - [ ] Смонтировать в бот-контейнер shared volume как `/agents` — каждый агент должен видеть свою поддиректорию как `/workspace` -- [ ] Добавить бот-сервис в свой compose (используйте `docker-compose.prod.yml` как шаблон сервиса) +- [ ] Добавить bot-only service в свой compose; агенты в этот compose не входят и управляются платформой --- @@ -94,6 +95,7 @@ cp .env.example .env | `MATRIX_USER_ID` | ✓ | `@bot:example.org` | | `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) | | `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна | +| `SURFACES_BOT_IMAGE` | ✓ | Docker image поверхности: `mput1/surfaces-bot:latest` | | `AGENT_BASE_URL` | | Fallback URL агента если `base_url` не задан в `matrix-agents.yaml` | | `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` | | `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) | @@ -117,31 +119,57 @@ agents: label: "Agent 1" base_url: "http://lambda.coredump.ru:7000/agent_1/" workspace_path: "/agents/1" + - id: agent-2 + label: "Agent 2" + base_url: "http://lambda.coredump.ru:7000/agent_2/" + workspace_path: "/agents/2" ``` - `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент. - `base_url` — HTTP URL агент-эндпоинта (path-based routing через reverse proxy). - `workspace_path` — путь к воркспейсу агента внутри бот-контейнера на shared volume. Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, агент пишет исходящие в свой `/workspace/`. +- Для 25-30 агентов продолжайте тот же паттерн: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`. Полный пример с комментариями: `config/matrix-agents.example.yaml` ### Production (bot-only) -`docker-compose.prod.yml` — шаблон сервиса `matrix-bot`. Платформа добавляет этот сервис в свой compose рядом с агент-контейнерами, монтирует shared volume и задаёт переменные окружения. +`docker-compose.prod.yml` — bot-only handoff через published image. Платформа добавляет этот сервис в свой compose рядом с agent containers, монтирует shared volume и задаёт переменные окружения. Этот compose не создаёт и не собирает агент-контейнеры. -Для изолированного запуска бота без агентов (smoke-тест): +Для запуска опубликованного image: ```bash -docker compose --env-file .env -f docker-compose.prod.yml up -d --build +export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest +docker compose --env-file .env -f docker-compose.prod.yml up -d ``` +Опубликованный image: + +```text +mput1/surfaces-bot:latest +sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be +``` + +Для сборки и публикации surface image: +```bash +docker login +export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest + +docker build --target production \ + --build-arg LAMBDA_AGENT_API_REF=master \ + -t "$SURFACES_BOT_IMAGE" . +docker push "$SURFACES_BOT_IMAGE" +``` + +Если push возвращает `insufficient_scope`, текущий Docker login не имеет доступа к namespace/repository. Создайте repository в нужном Docker Hub namespace или перетегируйте image в namespace пользователя, под которым выполнен `docker login`. + ### Fullstack E2E (bot + agent) ```bash docker compose --env-file .env -f docker-compose.fullstack.yml up --build ``` -Поднимает `matrix-bot` вместе с локальным `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте. +Поднимает `matrix-bot` вместе с локальным `platform-agent`. Это internal harness, не production topology на 25-30 агентов. `matrix-bot` собирается через Dockerfile target `development` и локальный `external/platform-agent_api` context, как в dev-сборке `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте. ### Сброс состояния (локально) @@ -159,8 +187,8 @@ Bot (/agents) Agent (/workspace = /agents/N/) /agents/0/output/ ←────────────────────────────────→ /workspace/output/ ``` -- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, передаёт агенту `attachments=["incoming/{stamp}-{file}"]` -- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file` и отправляет пользователю как Matrix file message +- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, например `/agents/17/incoming/report.pdf`, и передаёт агенту `attachments=["incoming/{stamp}-{file}"]` +- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file`, например `/agents/17/output/file`, и отправляет пользователю как Matrix file message - `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml` --- diff --git a/config/matrix-agents.example.yaml b/config/matrix-agents.example.yaml index 8696def..30d41a2 100644 --- a/config/matrix-agents.example.yaml +++ b/config/matrix-agents.example.yaml @@ -1,4 +1,6 @@ # Agent registry for the Matrix bot. +# Production target: one surface bot routes to 25-30 externally managed agents. +# Keep adding entries with the same base_url/workspace_path pattern. # # user_agents: maps a Matrix user ID to an agent ID. # If a user is not listed, the bot uses the first agent from the list below. @@ -17,6 +19,7 @@ user_agents: "@user0:matrix.example.org": agent-0 "@user1:matrix.example.org": agent-1 + "@user2:matrix.example.org": agent-2 agents: - id: agent-0 @@ -28,3 +31,14 @@ agents: label: "Agent 1" base_url: "http://lambda.coredump.ru:7000/agent_1/" workspace_path: "/agents/1" + + - id: agent-2 + label: "Agent 2" + base_url: "http://lambda.coredump.ru:7000/agent_2/" + workspace_path: "/agents/2" + + # Continue the same pattern through agent-29 for a 25-30 agent deployment: + # - id: agent-29 + # label: "Agent 29" + # base_url: "http://lambda.coredump.ru:7000/agent_29/" + # workspace_path: "/agents/29" diff --git a/docker-compose.fullstack.yml b/docker-compose.fullstack.yml index d412773..88ff37b 100644 --- a/docker-compose.fullstack.yml +++ b/docker-compose.fullstack.yml @@ -3,6 +3,16 @@ services: extends: file: docker-compose.prod.yml service: matrix-bot + build: + context: . + dockerfile: Dockerfile + target: development + args: + LAMBDA_AGENT_API_REF: ${LAMBDA_AGENT_API_REF:-master} + additional_contexts: + agent_api: ./external/platform-agent_api + tags: + - ${SURFACES_BOT_DEV_IMAGE:-surfaces-bot:dev} environment: AGENT_BASE_URL: http://platform-agent:8000 depends_on: diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index 04f37d8..2c7e942 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -1,6 +1,6 @@ services: matrix-bot: - build: . + image: "${SURFACES_BOT_IMAGE:?Set SURFACES_BOT_IMAGE to the pushed image, e.g. mput1/surfaces-bot:latest}" environment: MATRIX_HOMESERVER: ${MATRIX_HOMESERVER:-} MATRIX_USER_ID: ${MATRIX_USER_ID:-} diff --git a/docs/deploy-architecture.md b/docs/deploy-architecture.md index 8f0e896..0d9a872 100644 --- a/docs/deploy-architecture.md +++ b/docs/deploy-architecture.md @@ -7,10 +7,10 @@ ## Compose Artifacts - **Production deploy:** `docker-compose.prod.yml` - Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`. - Платформа предоставляет агент-контейнеры отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`. + Bot-only handoff через published image (`SURFACES_BOT_IMAGE`). Поднимает только `matrix-bot`, монтирует shared volume в `/agents`. + Платформа предоставляет 25-30 agent containers/services отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`. - **Internal full-stack E2E:** `docker-compose.fullstack.yml` - Внутренний harness для тестирования. Поднимает `matrix-bot` и один `platform-agent`, health-gated startup. + Внутренний harness для тестирования. Локально собирает `matrix-bot` через Dockerfile target `development`, поднимает один `platform-agent`, health-gated startup. Production operators: `docker-compose.prod.yml`. Internal E2E: `docker-compose.fullstack.yml`. @@ -33,7 +33,7 @@ lambda.coredump.ru ``` - **Один инстанс Matrix-бота** обслуживает всех пользователей. -- **Один агент-контейнер на пользователя.** Изоляция по agent_id, не через chat_id внутри одного инстанса. +- **Один агент-контейнер на пользователя.** Production scale target: 25-30 внешних агентов. Изоляция по `agent_id`, не через один общий agent instance. - **Shared volume** `/agents/` смонтирован в Matrix-бот. В internal full-stack harness тот же volume mounted as `/workspace` inside `platform-agent`, чтобы bot-side absolute paths и agent workspace относились к одному и тому же хранилищу. --- @@ -58,12 +58,49 @@ agents: label: "Agent 1" base_url: "http://lambda.coredump.ru:7000/agent_1/" workspace_path: "/agents/1" + + - id: agent-2 + label: "Agent 2" + base_url: "http://lambda.coredump.ru:7000/agent_2/" + workspace_path: "/agents/2" ``` - `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка. - `agents[].base_url` — HTTP URL агент-эндпоинта. Бот подключается через AgentApi. - `agents[].workspace_path` — абсолютный путь к воркспейсу агента **внутри контейнера бота** (т.е. на shared volume). Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, читает исходящие из `{workspace_path}/`. +- Для 25-30 агентов продолжайте тот же паттерн до нужного номера: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`. + +## Surface Image Build Contract + +Production image содержит только Matrix surface. Он не содержит `platform-agent` и не требует локального `external/` build context. + +```bash +docker login +export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest + +docker build --target production \ + --build-arg LAMBDA_AGENT_API_REF=master \ + -t "$SURFACES_BOT_IMAGE" . +docker push "$SURFACES_BOT_IMAGE" +``` + +Published image: + +```text +mput1/surfaces-bot:latest +sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be +``` + +`SURFACES_BOT_IMAGE` должен указывать на registry namespace, куда текущий Docker account может пушить. Ошибка `insufficient_scope` означает, что пользователь не залогинен в этот namespace, repository не создан, или у аккаунта нет push-доступа. + +Production Dockerfile ставит `platform/agent_api` из Git по тому же принципу, что и `platform-agent` production image: + +```bash +git+https://git.lambda.coredump.ru/platform/agent_api.git +``` + +Локальный `docker-compose.fullstack.yml` остаётся dev/E2E harness: он использует target `development` и `additional_contexts.agent_api=./external/platform-agent_api`, чтобы можно было тестировать surface вместе с локальным checkout SDK. --- diff --git a/tests/adapter/matrix/test_dispatcher.py b/tests/adapter/matrix/test_dispatcher.py index 338525d..1733b75 100644 --- a/tests/adapter/matrix/test_dispatcher.py +++ b/tests/adapter/matrix/test_dispatcher.py @@ -15,8 +15,10 @@ from nio import ( from nio.api import RoomVisibility from nio.responses import SyncResponse +from adapter.matrix.agent_registry import AgentDefinition, AgentRegistry from adapter.matrix.bot import MatrixBot, build_runtime, prepare_live_sync from adapter.matrix.handlers.auth import handle_invite +from adapter.matrix.routed_platform import RoutedPlatformClient from adapter.matrix.store import ( add_staged_attachment, get_platform_chat_id, @@ -36,7 +38,6 @@ from core.protocol import ( ) from sdk.interface import PlatformError from sdk.mock import MockPlatformClient -from adapter.matrix.routed_platform import RoutedPlatformClient async def test_matrix_dispatcher_registers_custom_handlers(): @@ -107,7 +108,10 @@ async def test_new_chat_creates_real_matrix_room_when_client_available(): assert client.room_create.await_count >= 1 client.room_put_state.assert_awaited_once() put_call = client.room_put_state.call_args - assert put_call.kwargs.get("room_id") == "!space:example" or put_call.args[0] == "!space:example" + assert ( + put_call.kwargs.get("room_id") == "!space:example" + or put_call.args[0] == "!space:example" + ) chats = await runtime.chat_mgr.list_active("u1") assert [c.chat_id for c in chats] == ["C7"] assert [c.surface_ref for c in chats] == ["!r2:example"] @@ -333,6 +337,119 @@ async def test_bot_downloads_matrix_file_to_workspace_before_staging(tmp_path, m bot._send_all.assert_not_awaited() +async def test_bot_downloads_matrix_file_to_configured_agent_workspace(tmp_path, monkeypatch): + monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path / "agents")) + runtime = build_runtime(platform=MockPlatformClient()) + runtime.registry = AgentRegistry( + [ + AgentDefinition( + agent_id="agent-17", + label="Agent 17", + base_url="http://lambda.coredump.ru:7000/agent_17/", + workspace_path=str(tmp_path / "agents" / "17"), + ) + ] + ) + await set_room_meta( + runtime.store, + "!chat17:example.org", + { + "chat_id": "C17", + "matrix_user_id": "@alice:example.org", + "platform_chat_id": "17", + "agent_id": "agent-17", + }, + ) + client = SimpleNamespace( + user_id="@bot:example.org", + download=AsyncMock(return_value=SimpleNamespace(body=b"%PDF-1.7")), + ) + bot = MatrixBot(client, runtime) + runtime.dispatcher.dispatch = AsyncMock(return_value=[]) + room = SimpleNamespace(room_id="!chat17:example.org") + event = SimpleNamespace( + sender="@alice:example.org", + body="report.pdf", + msgtype="m.file", + replyto_event_id=None, + url="mxc://server/id", + mimetype="application/pdf", + ) + + await bot.on_room_message(room, event) + + staged = await get_staged_attachments( + runtime.store, "!chat17:example.org", "@alice:example.org" + ) + assert staged[0]["workspace_path"].startswith("incoming/") + assert ( + tmp_path / "agents" / "17" / staged[0]["workspace_path"] + ).read_bytes() == b"%PDF-1.7" + + +async def test_bot_uploads_agent_output_from_configured_agent_workspace(tmp_path, monkeypatch): + monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path / "agents")) + output_file = tmp_path / "agents" / "17" / "output" / "result.txt" + output_file.parent.mkdir(parents=True) + output_file.write_text("ready", encoding="utf-8") + runtime = build_runtime(platform=MockPlatformClient()) + runtime.registry = AgentRegistry( + [ + AgentDefinition( + agent_id="agent-17", + label="Agent 17", + base_url="http://lambda.coredump.ru:7000/agent_17/", + workspace_path=str(tmp_path / "agents" / "17"), + ) + ] + ) + await set_room_meta( + runtime.store, + "!chat17:example.org", + { + "chat_id": "C17", + "matrix_user_id": "@alice:example.org", + "platform_chat_id": "17", + "agent_id": "agent-17", + }, + ) + client = SimpleNamespace( + user_id="@bot:example.org", + upload=AsyncMock(return_value=(SimpleNamespace(content_uri="mxc://server/result"), {})), + room_send=AsyncMock(), + ) + bot = MatrixBot(client, runtime) + runtime.dispatcher.dispatch = AsyncMock( + return_value=[ + OutgoingMessage( + chat_id="C17", + text="Файл готов", + attachments=[ + Attachment( + type="document", + filename="result.txt", + mime_type="text/plain", + workspace_path="output/result.txt", + ) + ], + ) + ] + ) + room = SimpleNamespace(room_id="!chat17:example.org") + event = SimpleNamespace( + sender="@alice:example.org", + body="сделай отчёт", + msgtype="m.text", + replyto_event_id=None, + ) + + await bot.on_room_message(room, event) + + uploaded_handle = client.upload.await_args.args[0] + assert uploaded_handle.name == str(output_file) + assert client.room_send.await_args_list[1].args[2]["url"] == "mxc://server/result" + + async def test_file_only_event_is_staged_and_does_not_dispatch(): runtime = build_runtime(platform=MockPlatformClient()) client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock()) diff --git a/tests/adapter/matrix/test_files.py b/tests/adapter/matrix/test_files.py index 71fb02f..674907d 100644 --- a/tests/adapter/matrix/test_files.py +++ b/tests/adapter/matrix/test_files.py @@ -3,7 +3,11 @@ from __future__ import annotations from pathlib import Path from types import SimpleNamespace -from adapter.matrix.files import build_workspace_attachment_path, download_matrix_attachment +from adapter.matrix.files import ( + build_agent_incoming_path, + build_workspace_attachment_path, + download_matrix_attachment, +) from core.protocol import Attachment @@ -65,3 +69,37 @@ def test_build_workspace_attachment_path_keeps_room_safe_agents_relative_contrac ) assert not Path(rel_path).is_absolute() assert abs_path == tmp_path / "agents" / "7" / rel_path + + +def test_build_agent_incoming_path_uses_agent_workspace_volume(tmp_path: Path): + rel_path, abs_path = build_agent_incoming_path( + workspace_root=tmp_path / "agents" / "17", + filename="quarterly status.pdf", + timestamp="20260428-110000", + ) + + assert rel_path == "incoming/20260428-110000-quarterly_status.pdf" + assert abs_path == tmp_path / "agents" / "17" / rel_path + + +async def test_download_matrix_attachment_uses_agent_workspace_incoming_dir(tmp_path: Path): + async def download(url: str): + assert url == "mxc://server/id" + return SimpleNamespace(body=b"%PDF-1.7") + + saved = await download_matrix_attachment( + client=SimpleNamespace(download=download), + workspace_root=tmp_path / "agents" / "17", + matrix_user_id="@alice:example.org", + room_id="!room:example.org", + attachment=Attachment( + type="document", + url="mxc://server/id", + filename="report.pdf", + mime_type="application/pdf", + ), + timestamp="20260428-110000", + ) + + assert saved.workspace_path == "incoming/20260428-110000-report.pdf" + assert (tmp_path / "agents" / "17" / saved.workspace_path).read_bytes() == b"%PDF-1.7" diff --git a/tests/test_deploy_handoff.py b/tests/test_deploy_handoff.py new file mode 100644 index 0000000..e2f3953 --- /dev/null +++ b/tests/test_deploy_handoff.py @@ -0,0 +1,62 @@ +from __future__ import annotations + +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parents[1] + + +def _compose(path: str) -> dict: + return yaml.safe_load((ROOT / path).read_text(encoding="utf-8")) + + +def test_prod_compose_uses_registry_image_not_local_build(): + prod = _compose("docker-compose.prod.yml") + service = prod["services"]["matrix-bot"] + + assert "image" in service + assert "build" not in service + assert service["image"].startswith("${SURFACES_BOT_IMAGE:?") + + +def test_fullstack_compose_keeps_local_dev_build_with_agent_api_context(): + fullstack = _compose("docker-compose.fullstack.yml") + service = fullstack["services"]["matrix-bot"] + + assert service["build"]["target"] == "development" + assert service["build"]["additional_contexts"]["agent_api"] == "./external/platform-agent_api" + assert service["extends"]["file"] == "docker-compose.prod.yml" + + +def test_dockerfile_production_build_does_not_require_local_external_tree(): + dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8") + + assert "/app/external/platform-agent_api" not in dockerfile + assert "external/platform-agent_api" not in dockerfile + assert "git+https://git.lambda.coredump.ru/platform/agent_api.git" in dockerfile + assert "python -m pip install --no-cache-dir --ignore-requires-python" in dockerfile + assert "uv pip install --system --ignore-requires-python" not in dockerfile + + +def test_dockerignore_excludes_local_only_and_runtime_artifacts(): + dockerignore = (ROOT / ".dockerignore").read_text(encoding="utf-8") + + assert "external/" in dockerignore + assert ".planning/" in dockerignore + assert "config/matrix-agents.yaml" in dockerignore + assert ".env" in dockerignore + + +def test_agent_registry_example_documents_multi_agent_volume_contract(): + registry = yaml.safe_load( + (ROOT / "config" / "matrix-agents.example.yaml").read_text(encoding="utf-8") + ) + agents = registry["agents"] + + assert len(agents) >= 3 + assert len({agent["id"] for agent in agents}) == len(agents) + assert len({agent["workspace_path"] for agent in agents}) == len(agents) + for index, agent in enumerate(agents): + assert agent["base_url"].endswith(f"/agent_{index}/") + assert agent["workspace_path"] == f"/agents/{index}" From 5679b9545091ef0f3a7d20444b35421b32e449d3 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 21:41:13 +0300 Subject: [PATCH 46/55] wip: phase 05 paused after deployment handoff --- .planning/HANDOFF.json | 98 ++++++++----------- .../05-mvp-deployment/.continue-here.md | 61 ++++++++++++ 2 files changed, 103 insertions(+), 56 deletions(-) create mode 100644 .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json index 853265c..e1e552c 100644 --- a/.planning/HANDOFF.json +++ b/.planning/HANDOFF.json @@ -1,100 +1,86 @@ { "version": "1.0", - "timestamp": "2026-04-27T18:44:51.832Z", + "timestamp": "2026-04-28T18:39:43.064Z", "phase": "05", - "phase_name": "deployment", - "phase_dir": null, - "plan": 0, + "phase_name": "MVP Deployment", + "phase_dir": ".planning/phases/05-mvp-deployment", + "plan": 4, "task": 0, "total_tasks": 0, - "status": "pre-planning", + "status": "paused", "completed_tasks": [ { "id": 1, - "name": "Research platform repos (agent, agent_api, master)", + "name": "Finalize multi-agent surface image handoff", "status": "done", - "commit": null + "commit": "5b53788" }, { "id": 2, - "name": "Clarify deployment topology with platform team", + "name": "Publish Docker image for the Matrix surface", "status": "done", - "commit": null + "artifact": "mput1/surfaces-bot:latest", + "digest": "sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be" }, { "id": 3, - "name": "Create docs/deploy-architecture.md", + "name": "Verify multi-agent file-volume routing contract", "status": "done", - "commit": null + "evidence": "tests cover /agents/17/incoming and /agents/17/output routing" } ], "remaining_tasks": [ - {"id": 4, "name": "Merge feat/matrix-direct-agent-prototype → main", "status": "not_started"}, - {"id": 5, "name": "Plan Phase 05 (deployment)", "status": "not_started"}, - {"id": 6, "name": "Execute Phase 05", "status": "not_started"} + { + "id": 1, + "name": "Platform team integrates the published surface image into their 25-30 agent deployment", + "status": "external" + }, + { + "id": 2, + "name": "Run a real platform smoke test with production Matrix credentials, matrix-agents.yaml, and shared /agents volume", + "status": "not_started" + } ], "blockers": [ { - "description": "agent_api #9-clientside-tool-call убирает attachments и MsgEventSendFile — если смержат до деплоя, сломает file transfer", + "description": "Full production verification depends on the platform team's real 25-30 agent orchestration and volume mounts.", "type": "external", - "workaround": "Используем master пока #9 не merged. Уточнить у Азамата сроки." - }, - { - "description": "AGENT_ID и COMPOSIO_API_KEY значения для каждого агента — нужны от платформы", - "type": "human_action", - "workaround": "Запросить у Азамата перед деплоем" + "workaround": "Use docker-compose.fullstack.yml only as local E2E harness; production uses mput1/surfaces-bot:latest plus platform-managed agents." } ], "human_actions_pending": [ { - "action": "Получить значения AGENT_ID и COMPOSIO_API_KEY для каждого агента от платформы", - "context": "Composio смержен в main platform-agent, теперь обязателен", + "action": "Send platform the image tag, digest, deploy docs, and matrix-agents.yaml contract", + "context": "The bot is published as a single surface container; platform supplies agents, base_url values, and /agents/N volume mounts.", "blocking": true }, { - "action": "Уточнить у Азамата сроки мержа agent_api #9 (убирает attachments/MsgEventSendFile)", - "context": "Мы строим file transfer на этих фичах из master", - "blocking": false - }, - { - "action": "Уточнить: chat_id=0 для всех или используем разные chat_id для C1/C2/C3", - "context": "Платформа показала пример с одним AgentApi на агента без явного chat_id", - "blocking": false + "action": "Platform prepares production config/matrix-agents.yaml", + "context": "Each external agent needs agent_id, base_url, and workspace_path such as /agents/17.", + "blocking": true } ], "decisions": [ { - "decision": "Один инстанс Matrix-бота на всех пользователей, один агент-контейнер на пользователя", - "rationale": "Подтверждено платформой. Reverse proxy на lambda.coredump.ru:7000 роутит по пути /agent_N/", - "phase": "pre-05" + "decision": "Ship one generic Matrix surface image, not a compose stack with 25-30 agents.", + "rationale": "The platform owns agent lifecycle/orchestration; the surface only needs base_url and workspace_path per agent.", + "phase": "05" }, { - "decision": "Файлы через shared volume /agents/, не через API", - "rationale": "Surface и агент видят один volume. Surface пишет файл → передаёт путь в attachments. Агент эмитит MsgEventSendFile → Surface читает файл и шлёт в Matrix", - "phase": "pre-05" + "decision": "Make SURFACES_BOT_IMAGE explicit and document the published mput1/surfaces-bot image.", + "rationale": "Docker Hub push access is namespace-specific; hardcoding mrkan0 caused insufficient_scope.", + "phase": "05" }, { - "decision": "Используем agent_api master (с attachments и MsgEventSendFile), не ветку #9", - "rationale": "master стабильный, #9 в разработке и убирает нужные нам фичи", - "phase": "pre-05" - }, - { - "decision": "Конфиг: два словаря — user_id→agent_id и agent_id→{base_url, workspace_path}", - "rationale": "Платформа подтвердила статический маппинг для MVP без Master", - "phase": "pre-05" - }, - { - "decision": "Master (platform-master feat/storage) не используем для MVP", - "rationale": "Ещё в разработке. Используем статический конфиг. При готовности Master — мигрируем.", - "phase": "pre-05" + "decision": "Keep docker-compose.fullstack.yml as internal E2E only.", + "rationale": "It validates the bot plus one local agent, but is not a model of production multi-agent orchestration.", + "phase": "05" } ], "uncommitted_files": [ - "docs/deploy-architecture.md", - "docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md", - "config/matrix-agents.yaml", - ".planning/STATE.md" + ".planning/HANDOFF.json", + ".planning/phases/05-mvp-deployment/.continue-here.md" ], - "next_action": "Запустить /gsd-plan-phase 05 для планирования фазы деплоя. Прочитать docs/deploy-architecture.md перед планированием.", - "context_notes": "Phase 04 полностью завершена, ветка feat/matrix-direct-agent-prototype готова к merge. Этот сеанс был посвящён архитектуре деплоя — исследовали платформу, обсуждали с командой. Всё что знаем про деплой — в docs/deploy-architecture.md. Phase 05 = деплой: обновить конфиг, sdk/real.py, добавить file transfer в Matrix адаптер, написать docker-compose." + "next_action": "Resume by coordinating platform integration: confirm they use mput1/surfaces-bot:latest, mount /agents, provide config/matrix-agents.yaml, then run a real Matrix smoke test.", + "context_notes": "Phase 05 implementation and handoff commit 5b53788 are pushed. The Docker image was successfully built and pushed by the user as mput1/surfaces-bot:latest with digest sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be. Existing unrelated .planning dirt and a local jpg remain in the worktree and were intentionally not included in the handoff commit." } diff --git a/.planning/phases/05-mvp-deployment/.continue-here.md b/.planning/phases/05-mvp-deployment/.continue-here.md new file mode 100644 index 0000000..f1013f0 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/.continue-here.md @@ -0,0 +1,61 @@ +--- +phase: 05-mvp-deployment +task: 0 +total_tasks: 0 +status: paused_after_handoff +last_updated: 2026-04-28T18:39:43.064Z +--- + + +Phase 05 implementation and deployment handoff are complete. The latest handoff commit is `5b53788` on `feat/deploy`, pushed to origin. The Matrix surface image was built and published as `mput1/surfaces-bot:latest` with digest `sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be`. + +The production model is one generic Matrix surface container connected to 25-30 externally managed platform agents. The surface does not start or manage agent containers. + + + + +- Finalized `docker-compose.prod.yml` as a bot-only handoff using required `SURFACES_BOT_IMAGE`. +- Kept `docker-compose.fullstack.yml` as internal E2E harness with one local `platform-agent` and local `agent_api` build context. +- Updated `Dockerfile` so production installs `platform/agent_api` from Git and no longer depends on local `external/`. +- Updated `.dockerignore` to keep `external/`, `.planning/`, tests, local runtime state, and real `config/matrix-agents.yaml` out of the image context. +- Updated `README.md`, `.env.example`, `docs/deploy-architecture.md`, and `config/matrix-agents.example.yaml` with the multi-agent contract. +- Added deploy contract tests and file-volume routing tests covering `/agents/17/incoming` and `/agents/17/output`. +- Verified handoff slice: `74 passed`, ruff clean, compose render clean, `git diff --check` clean. +- User built and pushed `mput1/surfaces-bot:latest` successfully. + + + + +- Send platform the published image tag/digest and the deploy contract: + - `mput1/surfaces-bot:latest` + - `sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be` + - one surface container, external 25-30 agents, routing through `config/matrix-agents.yaml` +- Platform must provide real `config/matrix-agents.yaml` with `agent_id`, `base_url`, and `workspace_path` for each agent. +- Platform must mount shared storage so bot-side `/agents/N` is the same storage each `agent_N` sees as `/workspace`. +- Run a real Matrix smoke test against platform-managed agents after the platform deploys the image. + + + + +- Ship one generic Matrix surface image instead of attempting to model 25-30 agent services in our production compose. +- Keep agent lifecycle, scaling, and orchestration owned by the platform. +- Use `SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest` as the documented image for handoff. +- Preserve `docker-compose.fullstack.yml` only as a local/internal E2E harness, not as production topology. +- Treat file exchange as a shared-volume contract: user files go to `{workspace_path}/incoming/...`; agent output is read from `{workspace_path}/output/...`. + + + + +- Full production verification is external: it requires the platform team's real 25-30 agent orchestration, reverse proxy routes, Matrix credentials, and volume mounts. +- Existing unrelated `.planning` changes and a local jpg remain in the worktree; they predate this pause and were not part of the deploy handoff commit. + + + +If resuming, do not re-open the old single-chat / DM-first deployment direction. The accepted model is Space+rooms, per-room `platform_chat_id`, one Matrix surface image, and external per-agent routing via `matrix-agents.yaml`. + +The likely next conversation with platform should be operational, not implementation-heavy: confirm they pull `mput1/surfaces-bot:latest`, mount `/agents`, provide `matrix-agents.yaml`, and run one user-to-agent file round trip. + + + +Start by sending platform the image tag/digest and the concise deployment checklist. Then coordinate the first real smoke test: one Matrix user mapped to one agent, text message, incoming file to `/agents/N/incoming`, outgoing file from `/agents/N/output`. + From 7e5f9c20a036f66debb36a6ad7614340c23ecd85 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Wed, 29 Apr 2026 00:07:25 +0300 Subject: [PATCH 47/55] wip: Phase 05 complete, amd64 image rebuilt --- .../05-mvp-deployment/.continue-here.md | 48 +++++-------------- 1 file changed, 13 insertions(+), 35 deletions(-) diff --git a/.planning/phases/05-mvp-deployment/.continue-here.md b/.planning/phases/05-mvp-deployment/.continue-here.md index f1013f0..5f0a722 100644 --- a/.planning/phases/05-mvp-deployment/.continue-here.md +++ b/.planning/phases/05-mvp-deployment/.continue-here.md @@ -1,61 +1,39 @@ --- phase: 05-mvp-deployment +phase_name: MVP deployment task: 0 total_tasks: 0 -status: paused_after_handoff -last_updated: 2026-04-28T18:39:43.064Z +status: completed +last_updated: 2026-04-28T21:07:17Z --- -Phase 05 implementation and deployment handoff are complete. The latest handoff commit is `5b53788` on `feat/deploy`, pushed to origin. The Matrix surface image was built and published as `mput1/surfaces-bot:latest` with digest `sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be`. - -The production model is one generic Matrix surface container connected to 25-30 externally managed platform agents. The surface does not start or manage agent containers. +Phase 05 deployment handoff is complete. Image rebuilt for linux/amd64 and handoff text prepared for platform team. -- Finalized `docker-compose.prod.yml` as a bot-only handoff using required `SURFACES_BOT_IMAGE`. -- Kept `docker-compose.fullstack.yml` as internal E2E harness with one local `platform-agent` and local `agent_api` build context. -- Updated `Dockerfile` so production installs `platform/agent_api` from Git and no longer depends on local `external/`. -- Updated `.dockerignore` to keep `external/`, `.planning/`, tests, local runtime state, and real `config/matrix-agents.yaml` out of the image context. -- Updated `README.md`, `.env.example`, `docs/deploy-architecture.md`, and `config/matrix-agents.example.yaml` with the multi-agent contract. -- Added deploy contract tests and file-volume routing tests covering `/agents/17/incoming` and `/agents/17/output`. -- Verified handoff slice: `74 passed`, ruff clean, compose render clean, `git diff --check` clean. -- User built and pushed `mput1/surfaces-bot:latest` successfully. +- Rebuilt image for linux/amd64 (was arm64 only): `mput1/surfaces-bot:latest` +- Updated deploy handoff digest in .continue-here.md +- Prepared deployment checklist text for platform -- Send platform the published image tag/digest and the deploy contract: - - `mput1/surfaces-bot:latest` - - `sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be` - - one surface container, external 25-30 agents, routing through `config/matrix-agents.yaml` -- Platform must provide real `config/matrix-agents.yaml` with `agent_id`, `base_url`, and `workspace_path` for each agent. -- Platform must mount shared storage so bot-side `/agents/N` is the same storage each `agent_N` sees as `/workspace`. -- Run a real Matrix smoke test against platform-managed agents after the platform deploys the image. +- Platform needs to pull image and deploy +- Awaiting smoke test confirmation from platform side -- Ship one generic Matrix surface image instead of attempting to model 25-30 agent services in our production compose. -- Keep agent lifecycle, scaling, and orchestration owned by the platform. -- Use `SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest` as the documented image for handoff. -- Preserve `docker-compose.fullstack.yml` only as a local/internal E2E harness, not as production topology. -- Treat file exchange as a shared-volume contract: user files go to `{workspace_path}/incoming/...`; agent output is read from `{workspace_path}/output/...`. +- Rebuild for amd64 to match platform's production environment -- Full production verification is external: it requires the platform team's real 25-30 agent orchestration, reverse proxy routes, Matrix credentials, and volume mounts. -- Existing unrelated `.planning` changes and a local jpg remain in the worktree; they predate this pause and were not part of the deploy handoff commit. +- None — implementation complete, awaiting platform deployment - -If resuming, do not re-open the old single-chat / DM-first deployment direction. The accepted model is Space+rooms, per-room `platform_chat_id`, one Matrix surface image, and external per-agent routing via `matrix-agents.yaml`. - -The likely next conversation with platform should be operational, not implementation-heavy: confirm they pull `mput1/surfaces-bot:latest`, mount `/agents`, provide `matrix-agents.yaml`, and run one user-to-agent file round trip. - - -Start by sending platform the image tag/digest and the concise deployment checklist. Then coordinate the first real smoke test: one Matrix user mapped to one agent, text message, incoming file to `/agents/N/incoming`, outgoing file from `/agents/N/output`. - +Await platform deployment confirmation. No further implementation work needed until platform reports issues or requests changes. + \ No newline at end of file From 63697218764e451405541df7e3f8ea1c8a42fd06 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Thu, 30 Apr 2026 18:04:24 +0300 Subject: [PATCH 48/55] wip: 05-mvp-deployment paused at task 0/0 --- .planning/HANDOFF.json | 88 ++++++++++++------- .../05-mvp-deployment/.continue-here.md | 47 +++++++--- 2 files changed, 93 insertions(+), 42 deletions(-) diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json index e1e552c..8e89043 100644 --- a/.planning/HANDOFF.json +++ b/.planning/HANDOFF.json @@ -1,86 +1,114 @@ { "version": "1.0", - "timestamp": "2026-04-28T18:39:43.064Z", + "timestamp": "2026-04-30T15:03:14Z", "phase": "05", - "phase_name": "MVP Deployment", + "phase_name": "MVP deployment", "phase_dir": ".planning/phases/05-mvp-deployment", - "plan": 4, + "plan": 0, "task": 0, "total_tasks": 0, "status": "paused", "completed_tasks": [ { "id": 1, - "name": "Finalize multi-agent surface image handoff", + "name": "Fix path-based base_url normalization and add WS debug visibility", "status": "done", - "commit": "5b53788" + "commit": "7e5f9c2" }, { "id": 2, - "name": "Publish Docker image for the Matrix surface", + "name": "Add Matrix room recovery, reinvite flow, and default-agent warning behavior", "status": "done", - "artifact": "mput1/surfaces-bot:latest", - "digest": "sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be" + "commit": "7e5f9c2" }, { "id": 3, - "name": "Verify multi-agent file-volume routing contract", + "name": "Switch user file handling to workspace-root filenames with copy-style collision suffixes", "status": "done", - "evidence": "tests cover /agents/17/incoming and /agents/17/output routing" + "commit": "7e5f9c2" + }, + { + "id": 4, + "name": "Verify recent routing incident cause", + "status": "done", + "progress": "Confirmed that config lookup is exact-MXID based; mismatch in homeserver suffix caused fallback to the first agent." } ], "remaining_tasks": [ { - "id": 1, - "name": "Platform team integrates the published surface image into their 25-30 agent deployment", - "status": "external" + "id": 5, + "name": "Build and publish a fresh production image with the current workspace-root attachment contract", + "status": "not_started" }, { - "id": 2, - "name": "Run a real platform smoke test with production Matrix credentials, matrix-agents.yaml, and shared /agents volume", + "id": 6, + "name": "Send the new digest to platform and request Matrix bot redeploy", "status": "not_started" } ], "blockers": [ { - "description": "Full production verification depends on the platform team's real 25-30 agent orchestration and volume mounts.", + "description": "Platform redeploy is still required after the next image publish.", "type": "external", - "workaround": "Use docker-compose.fullstack.yml only as local E2E harness; production uses mput1/surfaces-bot:latest plus platform-managed agents." + "workaround": "None until a fresh digest is published." + }, + { + "description": "Old Phase 04 planning files still contain placeholder content.", + "type": "technical", + "workaround": "Ignore for the current deploy task; clean later as planning debt." } ], "human_actions_pending": [ { - "action": "Send platform the image tag, digest, deploy docs, and matrix-agents.yaml contract", - "context": "The bot is published as a single surface container; platform supplies agents, base_url values, and /agents/N volume mounts.", + "action": "Use exact Matrix MXIDs in user_agents, including the real homeserver suffix.", + "context": "Routing fallback to the first agent occurs whenever the config key does not exactly match the sender.", "blocking": true }, { - "action": "Platform prepares production config/matrix-agents.yaml", - "context": "Each external agent needs agent_id, base_url, and workspace_path such as /agents/17.", + "action": "Redeploy matrix-bot after the new image is published.", + "context": "Config edits alone need a container restart; the file-contract code change needs a new image first.", "blocking": true } ], "decisions": [ { - "decision": "Ship one generic Matrix surface image, not a compose stack with 25-30 agents.", - "rationale": "The platform owns agent lifecycle/orchestration; the surface only needs base_url and workspace_path per agent.", + "decision": "Keep fallback to the first agent for users missing from user_agents.", + "rationale": "Platform wanted that behavior to remain available, but with explicit user warning.", "phase": "05" }, { - "decision": "Make SURFACES_BOT_IMAGE explicit and document the published mput1/surfaces-bot image.", - "rationale": "Docker Hub push access is namespace-specific; hardcoding mrkan0 caused insufficient_scope.", + "decision": "Require exact Matrix MXID matching in user_agents.", + "rationale": "Current routing is deterministic and simple; no fuzzy matching or homeserver aliasing was introduced.", "phase": "05" }, { - "decision": "Keep docker-compose.fullstack.yml as internal E2E only.", - "rationale": "It validates the bot plus one local agent, but is not a model of production multi-agent orchestration.", + "decision": "Use workspace-root filenames for incoming user files and Windows-style copy suffixes on collision.", + "rationale": "Platform requested removal of incoming/outgoing directory split and timestamp-prefixed names.", "phase": "05" } ], "uncommitted_files": [ ".planning/HANDOFF.json", - ".planning/phases/05-mvp-deployment/.continue-here.md" + ".planning/STATE.md", + ".planning/phases/05-mvp-deployment/.continue-here.md", + "README.md", + "adapter/matrix/agent_registry.py", + "adapter/matrix/bot.py", + "adapter/matrix/files.py", + "adapter/matrix/handlers/auth.py", + "adapter/matrix/handlers/chat.py", + "adapter/matrix/reconciliation.py", + "adapter/matrix/routed_platform.py", + "config/matrix-agents.example.yaml", + "docs/deploy-architecture.md", + "sdk/real.py", + "tests/adapter/matrix/test_dispatcher.py", + "tests/adapter/matrix/test_files.py", + "tests/adapter/matrix/test_invite_space.py", + "tests/adapter/matrix/test_reconciliation.py", + "tests/platform/test_real.py", + "tests/test_deploy_handoff.py" ], - "next_action": "Resume by coordinating platform integration: confirm they use mput1/surfaces-bot:latest, mount /agents, provide config/matrix-agents.yaml, then run a real Matrix smoke test.", - "context_notes": "Phase 05 implementation and handoff commit 5b53788 are pushed. The Docker image was successfully built and pushed by the user as mput1/surfaces-bot:latest with digest sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be. Existing unrelated .planning dirt and a local jpg remain in the worktree and were intentionally not included in the handoff commit." + "next_action": "Build and publish a fresh production image from the current worktree, then send the digest to the platform for redeploy.", + "context_notes": "Current runtime logic appears correct. The last reported routing bug was traced to config mismatch between the real Matrix sender and the user_agents key. Do not reuse the previously published recovery image for deployment because it does not include the final workspace-root file contract." } diff --git a/.planning/phases/05-mvp-deployment/.continue-here.md b/.planning/phases/05-mvp-deployment/.continue-here.md index 5f0a722..25fefb4 100644 --- a/.planning/phases/05-mvp-deployment/.continue-here.md +++ b/.planning/phases/05-mvp-deployment/.continue-here.md @@ -3,37 +3,60 @@ phase: 05-mvp-deployment phase_name: MVP deployment task: 0 total_tasks: 0 -status: completed -last_updated: 2026-04-28T21:07:17Z +status: paused +last_updated: 2026-04-30T15:03:14Z --- -Phase 05 deployment handoff is complete. Image rebuilt for linux/amd64 and handoff text prepared for platform team. +Phase 05 code changes are in place, but the latest workspace-root attachment contract is not yet published in a new production image. Today's last debugging step confirmed that the user-to-agent config itself was fine except for one exact-MXID mismatch: the homeserver suffix in `user_agents` did not match the real Matrix sender, so fallback to the first agent was expected. -- Rebuilt image for linux/amd64 (was arm64 only): `mput1/surfaces-bot:latest` -- Updated deploy handoff digest in .continue-here.md -- Prepared deployment checklist text for platform +- Fixed the path-based `base_url` normalization bug that caused WS connects to drop route prefixes. +- Added WS lifecycle debug logging behind `SURFACES_DEBUG_WS=1`. +- Added Matrix routing/recovery behavior: +- warning users when they are not listed in `user_agents` +- preserving room bindings across config updates +- re-inviting users back into their Space and active rooms after leave +- `!new` from the entry/DM room to create a fresh working chat +- Reworked attachment handling so user files now go directly into the agent workspace root with Windows-style collision suffixes like `file (1).pdf`. +- Updated docs and tests to match the new root-workspace file contract. +- Verified that the recent “still goes to default agent” report was caused by exact MXID mismatch in config, not by YAML parsing or runtime routing logic. +- Published earlier images: +- `mput1/surfaces-bot:debug-ws-20260429` +- `mput1/surfaces-bot:matrix-recovery-20260429` -- Platform needs to pull image and deploy -- Awaiting smoke test confirmation from platform side +- Build and publish a new production image that includes the latest workspace-root attachment changes. +- Give the platform the new digest and ask them to redeploy the Matrix bot container. +- Optionally run local smoke/fullstack validation once more before publishing if extra confidence is needed. -- Rebuild for amd64 to match platform's production environment +- Keep the fallback to the first agent when a user is missing from `user_agents`. +- Require exact Matrix MXID match in `user_agents`; no fuzzy matching or homeserver normalization was added. +- Warn the user in-band when default-agent fallback is used. +- Keep room identity and `platform_chat_id` stable across config updates. +- Require container restart for config changes; no image rebuild is needed for `matrix-agents.yaml` edits alone. +- Remove `incoming/` and timestamp prefixes from the attachment contract. +- Save uploaded user files directly at the workspace root and resolve collisions with copy-style suffixes. -- None — implementation complete, awaiting platform deployment +- No code blocker. +- External dependency: platform redeploy after the next image publish. +- Historical debt: placeholder summary/plan artifacts still exist in old Phase 04 files and were not cleaned during this session. + +The current codebase should route correctly if the deployed config uses the exact real Matrix sender IDs, e.g. `@user:matrix.lambda.coredump.ru`. The next likely mistake during resume would be publishing the wrong image digest: the currently published recovery image predates the latest file-contract change. Resume by building a fresh image from the current worktree, not by reusing the old digest. + + -Await platform deployment confirmation. No further implementation work needed until platform reports issues or requests changes. - \ No newline at end of file +Rebuild the production image from the current worktree, publish it, and send the new digest to the platform for redeploy. + From 0f79494fbe215b1392088bce0b1648618cf7206e Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sat, 2 May 2026 23:45:52 +0300 Subject: [PATCH 49/55] feat(deploy): finalize MVP deployment and file transfer approach --- .planning/HANDOFF.json | 114 --- .planning/PROJECT.md | 4 +- .planning/STATE.md | 15 +- .../.continue-here.md | 53 -- .../05-mvp-deployment/.continue-here.md | 62 -- .../phases/05-mvp-deployment/05-01-PLAN.md | 158 ++++ .../phases/05-mvp-deployment/05-01-SUMMARY.md | 99 ++ .../phases/05-mvp-deployment/05-02-PLAN.md | 156 ++++ .../phases/05-mvp-deployment/05-03-PLAN.md | 145 +++ .../phases/05-mvp-deployment/05-04-PLAN.md | 128 +++ .../phases/05-mvp-deployment/05-CONTEXT.md | 157 ---- .../05-mvp-deployment/05-DISCUSSION-LOG.md | 65 -- .../phases/05-mvp-deployment/05-VALIDATION.md | 67 +- Dockerfile | 14 +- README.md | 27 +- adapter/matrix/agent_registry.py | 19 + adapter/matrix/bot.py | 208 ++++- adapter/matrix/files.py | 80 +- adapter/matrix/handlers/auth.py | 116 ++- adapter/matrix/handlers/chat.py | 14 +- adapter/matrix/reconciliation.py | 37 +- adapter/matrix/routed_platform.py | 25 +- config/matrix-agents.example.yaml | 2 +- config/matrix-agents.smoke.yaml | 10 + docker-compose.smoke.timeout.yml | 18 + docker-compose.smoke.yml | 109 +++ docker/nginx/smoke-agents-timeout.conf | 28 + docker/nginx/smoke-agents.conf | 28 + docs/deploy-architecture.md | 13 +- docs/max-surface-guide.md | 340 +++++++ ...x-multi-agent-routing-and-restart-state.md | 855 ++++++++++++++++++ sdk/real.py | 35 +- ...oud-photo-size-2-5440546240941724952-y.jpg | Bin 0 -> 49274 bytes tests/adapter/matrix/test_dispatcher.py | 14 +- tests/adapter/matrix/test_files.py | 77 +- tests/adapter/matrix/test_invite_space.py | 49 +- tests/adapter/matrix/test_reconciliation.py | 50 + tests/platform/test_real.py | 39 +- tests/test_check_matrix_agents.py | 22 + tests/test_deploy_handoff.py | 40 + tools/__init__.py | 1 + tools/check_matrix_agents.py | 197 ++++ tools/no_status_agent.py | 33 + 43 files changed, 3078 insertions(+), 645 deletions(-) delete mode 100644 .planning/HANDOFF.json delete mode 100644 .planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md delete mode 100644 .planning/phases/05-mvp-deployment/.continue-here.md create mode 100644 .planning/phases/05-mvp-deployment/05-01-PLAN.md create mode 100644 .planning/phases/05-mvp-deployment/05-01-SUMMARY.md create mode 100644 .planning/phases/05-mvp-deployment/05-02-PLAN.md create mode 100644 .planning/phases/05-mvp-deployment/05-03-PLAN.md create mode 100644 .planning/phases/05-mvp-deployment/05-04-PLAN.md delete mode 100644 .planning/phases/05-mvp-deployment/05-CONTEXT.md delete mode 100644 .planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md create mode 100644 config/matrix-agents.smoke.yaml create mode 100644 docker-compose.smoke.timeout.yml create mode 100644 docker-compose.smoke.yml create mode 100644 docker/nginx/smoke-agents-timeout.conf create mode 100644 docker/nginx/smoke-agents.conf create mode 100644 docs/max-surface-guide.md create mode 100644 docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md create mode 100644 telegram-cloud-photo-size-2-5440546240941724952-y.jpg create mode 100644 tests/test_check_matrix_agents.py create mode 100644 tools/__init__.py create mode 100644 tools/check_matrix_agents.py create mode 100644 tools/no_status_agent.py diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json deleted file mode 100644 index 8e89043..0000000 --- a/.planning/HANDOFF.json +++ /dev/null @@ -1,114 +0,0 @@ -{ - "version": "1.0", - "timestamp": "2026-04-30T15:03:14Z", - "phase": "05", - "phase_name": "MVP deployment", - "phase_dir": ".planning/phases/05-mvp-deployment", - "plan": 0, - "task": 0, - "total_tasks": 0, - "status": "paused", - "completed_tasks": [ - { - "id": 1, - "name": "Fix path-based base_url normalization and add WS debug visibility", - "status": "done", - "commit": "7e5f9c2" - }, - { - "id": 2, - "name": "Add Matrix room recovery, reinvite flow, and default-agent warning behavior", - "status": "done", - "commit": "7e5f9c2" - }, - { - "id": 3, - "name": "Switch user file handling to workspace-root filenames with copy-style collision suffixes", - "status": "done", - "commit": "7e5f9c2" - }, - { - "id": 4, - "name": "Verify recent routing incident cause", - "status": "done", - "progress": "Confirmed that config lookup is exact-MXID based; mismatch in homeserver suffix caused fallback to the first agent." - } - ], - "remaining_tasks": [ - { - "id": 5, - "name": "Build and publish a fresh production image with the current workspace-root attachment contract", - "status": "not_started" - }, - { - "id": 6, - "name": "Send the new digest to platform and request Matrix bot redeploy", - "status": "not_started" - } - ], - "blockers": [ - { - "description": "Platform redeploy is still required after the next image publish.", - "type": "external", - "workaround": "None until a fresh digest is published." - }, - { - "description": "Old Phase 04 planning files still contain placeholder content.", - "type": "technical", - "workaround": "Ignore for the current deploy task; clean later as planning debt." - } - ], - "human_actions_pending": [ - { - "action": "Use exact Matrix MXIDs in user_agents, including the real homeserver suffix.", - "context": "Routing fallback to the first agent occurs whenever the config key does not exactly match the sender.", - "blocking": true - }, - { - "action": "Redeploy matrix-bot after the new image is published.", - "context": "Config edits alone need a container restart; the file-contract code change needs a new image first.", - "blocking": true - } - ], - "decisions": [ - { - "decision": "Keep fallback to the first agent for users missing from user_agents.", - "rationale": "Platform wanted that behavior to remain available, but with explicit user warning.", - "phase": "05" - }, - { - "decision": "Require exact Matrix MXID matching in user_agents.", - "rationale": "Current routing is deterministic and simple; no fuzzy matching or homeserver aliasing was introduced.", - "phase": "05" - }, - { - "decision": "Use workspace-root filenames for incoming user files and Windows-style copy suffixes on collision.", - "rationale": "Platform requested removal of incoming/outgoing directory split and timestamp-prefixed names.", - "phase": "05" - } - ], - "uncommitted_files": [ - ".planning/HANDOFF.json", - ".planning/STATE.md", - ".planning/phases/05-mvp-deployment/.continue-here.md", - "README.md", - "adapter/matrix/agent_registry.py", - "adapter/matrix/bot.py", - "adapter/matrix/files.py", - "adapter/matrix/handlers/auth.py", - "adapter/matrix/handlers/chat.py", - "adapter/matrix/reconciliation.py", - "adapter/matrix/routed_platform.py", - "config/matrix-agents.example.yaml", - "docs/deploy-architecture.md", - "sdk/real.py", - "tests/adapter/matrix/test_dispatcher.py", - "tests/adapter/matrix/test_files.py", - "tests/adapter/matrix/test_invite_space.py", - "tests/adapter/matrix/test_reconciliation.py", - "tests/platform/test_real.py", - "tests/test_deploy_handoff.py" - ], - "next_action": "Build and publish a fresh production image from the current worktree, then send the digest to the platform for redeploy.", - "context_notes": "Current runtime logic appears correct. The last reported routing bug was traced to config mismatch between the real Matrix sender and the user_agents key. Do not reuse the previously published recovery image for deployment because it does not include the final workspace-root file contract." -} diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index a8043bd..9c859f8 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -14,7 +14,7 @@ Telegram и Matrix боты для взаимодействия пользова - ✓ core/ — унифицированный протокол событий, EventDispatcher, StateStore, ChatManager, AuthManager, SettingsManager — existing - ✓ adapter/telegram/ — forum-first адаптер (Threaded Mode), `/start`, `/new`, `/archive`, `/rename`, `/settings`, стриминг ответов — existing, QA passed -- ✓ adapter/matrix/ — DM-first адаптер, invite flow, `!new`, `!skills`, `!soul`, `!safety`, room-per-chat — existing +- ✓ adapter/matrix/ — Space+rooms адаптер, invite flow, `!new`, `!archive`, `!rename`, `!settings`, room-per-chat — existing - ✓ sdk/mock.py — MockPlatformClient: `stream_message`, `get_or_create_user`, `get_settings`, `update_settings` — existing ### Active @@ -50,7 +50,7 @@ Telegram и Matrix боты для взаимодействия пользова | Forum-first (Threaded Mode) для Telegram | Bot API 9.3 позволяет личный чат как форум — чище, без суперпруппы | ✓ Good | | (user_id, thread_id) как PK в chats | Изоляция контекстов по топику | ✓ Good | | MockPlatformClient через sdk/interface.py | Не ждать SDK, разрабатывать независимо | ✓ Good | -| DM-first для Matrix (не Space-first) | Space lifecycle слишком сложен для первого этапа | ✓ Good | +| Space+rooms для Matrix | Room-based UX и явные чаты важнее DM-first упрощений | ✓ Good | | Отказ от E2EE в Matrix | python-olm не собирается на macOS/ARM | — Pending | ## Evolution diff --git a/.planning/STATE.md b/.planning/STATE.md index 818b085..eb05f42 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,8 +2,8 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Phase 05 Complete -last_updated: "2026-04-27T22:17:10.233Z" +status: Phase 05 Paused +last_updated: "2026-04-29T08:49:04Z" progress: total_phases: 6 completed_phases: 3 @@ -18,11 +18,13 @@ progress: See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра -**Current focus:** Phase 05 complete — MVP deployment handoff is ready +**Current focus:** Phase 05 paused — latest file-contract change needs a new image build before platform redeploy ## Current Phase -**Phase 05** complete: MVP deployment hardening +**Phase 05** paused: MVP deployment hardening is in place, but the latest attachment workspace-root change is not yet published + +Deployment handoff follow-up is external. The last published image predates the latest file-handling change; the next step is to rebuild and publish a fresh image, then ask the platform to redeploy Matrix with the shared `/agents` volumes and `config/matrix-agents.yaml`. Plan `05-01` is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy `platform_chat_id` bindings on restart. @@ -90,6 +92,7 @@ Verified with `docker compose -f docker-compose.prod.yml config`, `docker compos ## Blockers - Lambda platform SDK не готов — Phase 2 заблокирована до готовности платформы +- Full production verification depends on the platform team's real multi-agent orchestration, production Matrix credentials, `config/matrix-agents.yaml`, and shared `/agents/N` volume mounts. ## Accumulated Context @@ -121,6 +124,6 @@ Verified with `docker compose -f docker-compose.prod.yml config`, `docker compos ## Session -- Last session: 2026-04-27T22:17:10Z -- Stopped at: Completed 05-04-PLAN.md +- Last session: 2026-04-29T08:49:04Z +- Stopped at: Handoff updated after attachment workspace-root change; waiting for image rebuild and platform redeploy - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md b/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md deleted file mode 100644 index c1b108a..0000000 --- a/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -context: phase -phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma -task: 4 -total_tasks: 6 -status: in_progress -last_updated: 2026-04-24T12:16:09.301Z ---- - - -Debugging first-chunk truncation bug in Matrix bot. Logging added to both sdk/real.py and external/platform-agent/src/agent/service.py. Waiting for user to run docker compose up --build and share platform-agent logs with stream_event lines. - - - - -- docker-compose.yml: added `./config:/app/config:ro` volume mount so MATRIX_AGENT_REGISTRY_PATH works -- config/matrix-agents.example.yaml: updated labels to Platform/Media -- sdk/real.py: added structlog debug logging in _stream_agent_events (logs each chunk index + text[:40]) -- external/platform-agent/src/agent/service.py: added logging of langgraph_node, content_type, content[:60] for every on_chat_model_stream event - -Bot is running and user confirmed it starts correctly with MATRIX_PLATFORM_BACKEND=real. - - - - -- Task 4: Get platform-agent debug logs (docker compose up --build, reproduce truncation, share stream_event lines) -- Task 5: Analyze: check content_type (str vs list), check langgraph_node (which graph node produces the first chunk) -- Task 6: Fix service.py based on findings - - - - -- Bug confirmed to be in platform-agent, NOT in surfaces bot: our sdk/real.py logs show chunk index=0 already has truncated text (e.g. ' Д Е Ё...' instead of 'А Б В Г Д...') -- deepagents framework uses SubAgentMiddleware: main dispatcher agent + general-purpose subagent -- service.py processes ALL on_chat_model_stream events from astream_events v2 with no node filtering -- Two leading hypotheses: (A) chunk.content is a list for some events (multimodal), causing silent skip/error; (B) events from wrong graph node are being captured/not captured - - - -- Need user to run docker compose up --build and share platform-agent logs with DEBUG output - - - -The deepagents architecture: create_deep_agent creates a main orchestrator with SubAgentMiddleware wrapping a general-purpose subagent. When astream_events v2 runs, it may emit on_chat_model_stream from both the main agent's LLM call AND the subagent's LLM call. service.py captures ALL of them. The first chunk of the actual response might be from the subagent (not forwarded to client properly), while the main agent's response starts mid-sentence because it "sees" the subagent's output in its tool result context. - -Two key things to look for in logs: -1. content_type=list → fix is `chunk.content[0].get("text", "")` or similar -2. langgraph_node varies between chunks → fix is to filter to the correct node (e.g. only "agent" node) - - - -Start with: docker compose up --build. Then send a message with image context (e.g. send an image first, then ask 'Напомни алфавит'). Share platform-agent-1 logs — specifically the stream_event lines showing ns= and content_type= values. - diff --git a/.planning/phases/05-mvp-deployment/.continue-here.md b/.planning/phases/05-mvp-deployment/.continue-here.md deleted file mode 100644 index 25fefb4..0000000 --- a/.planning/phases/05-mvp-deployment/.continue-here.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -phase: 05-mvp-deployment -phase_name: MVP deployment -task: 0 -total_tasks: 0 -status: paused -last_updated: 2026-04-30T15:03:14Z ---- - - -Phase 05 code changes are in place, but the latest workspace-root attachment contract is not yet published in a new production image. Today's last debugging step confirmed that the user-to-agent config itself was fine except for one exact-MXID mismatch: the homeserver suffix in `user_agents` did not match the real Matrix sender, so fallback to the first agent was expected. - - - - -- Fixed the path-based `base_url` normalization bug that caused WS connects to drop route prefixes. -- Added WS lifecycle debug logging behind `SURFACES_DEBUG_WS=1`. -- Added Matrix routing/recovery behavior: -- warning users when they are not listed in `user_agents` -- preserving room bindings across config updates -- re-inviting users back into their Space and active rooms after leave -- `!new` from the entry/DM room to create a fresh working chat -- Reworked attachment handling so user files now go directly into the agent workspace root with Windows-style collision suffixes like `file (1).pdf`. -- Updated docs and tests to match the new root-workspace file contract. -- Verified that the recent “still goes to default agent” report was caused by exact MXID mismatch in config, not by YAML parsing or runtime routing logic. -- Published earlier images: -- `mput1/surfaces-bot:debug-ws-20260429` -- `mput1/surfaces-bot:matrix-recovery-20260429` - - - - -- Build and publish a new production image that includes the latest workspace-root attachment changes. -- Give the platform the new digest and ask them to redeploy the Matrix bot container. -- Optionally run local smoke/fullstack validation once more before publishing if extra confidence is needed. - - - - -- Keep the fallback to the first agent when a user is missing from `user_agents`. -- Require exact Matrix MXID match in `user_agents`; no fuzzy matching or homeserver normalization was added. -- Warn the user in-band when default-agent fallback is used. -- Keep room identity and `platform_chat_id` stable across config updates. -- Require container restart for config changes; no image rebuild is needed for `matrix-agents.yaml` edits alone. -- Remove `incoming/` and timestamp prefixes from the attachment contract. -- Save uploaded user files directly at the workspace root and resolve collisions with copy-style suffixes. - - - - -- No code blocker. -- External dependency: platform redeploy after the next image publish. -- Historical debt: placeholder summary/plan artifacts still exist in old Phase 04 files and were not cleaned during this session. - - - -The current codebase should route correctly if the deployed config uses the exact real Matrix sender IDs, e.g. `@user:matrix.lambda.coredump.ru`. The next likely mistake during resume would be publishing the wrong image digest: the currently published recovery image predates the latest file-contract change. Resume by building a fresh image from the current worktree, not by reusing the old digest. - - - -Rebuild the production image from the current worktree, publish it, and send the new digest to the platform for redeploy. - diff --git a/.planning/phases/05-mvp-deployment/05-01-PLAN.md b/.planning/phases/05-mvp-deployment/05-01-PLAN.md new file mode 100644 index 0000000..2320eda --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-01-PLAN.md @@ -0,0 +1,158 @@ +--- +phase: 05-mvp-deployment +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - adapter/matrix/reconciliation.py + - adapter/matrix/bot.py + - tests/adapter/matrix/test_reconciliation.py + - tests/adapter/matrix/test_restart_persistence.py +autonomous: true +requirements: + - PH05-01 + - PH05-03 +must_haves: + truths: + - "On restart, existing Matrix Space and child-room topology is rebuilt before live sync begins." + - "Restart recovery preserves Space+rooms UX instead of creating duplicate DM-style working rooms." + - "Recovered rooms regain user metadata, room metadata, and chat bindings needed for normal routing." + - "Legacy working rooms missing `platform_chat_id` are backfilled deterministically during startup before strict routing handles traffic." + artifacts: + - path: "adapter/matrix/reconciliation.py" + provides: "Authoritative restart reconciliation from Matrix topology into local metadata" + - path: "adapter/matrix/bot.py" + provides: "Startup wiring that runs reconciliation before sync_forever" + - path: "tests/adapter/matrix/test_reconciliation.py" + provides: "Regression coverage for startup recovery and idempotence" + key_links: + - from: "adapter/matrix/bot.py" + to: "adapter/matrix/reconciliation.py" + via: "startup bootstrap before sync_forever" + pattern: "reconcil" + - from: "adapter/matrix/reconciliation.py" + to: "core/chat.py" + via: "chat manager rebuild for recovered rooms" + pattern: "get_or_create" +--- + + +Rebuild Matrix-local routing state from authoritative Space topology before the bot processes live traffic. + +Purpose: Preserve the Phase 01 Space+rooms contract after restart even if SQLite metadata is partial or missing. +Output: A startup reconciliation module, bot wiring, and regression tests proving no DM-first duplication on restart. + + + +@/Users/a/.codex/get-shit-done/workflows/execute-plan.md +@/Users/a/.codex/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/05-mvp-deployment/05-RESEARCH.md +@.planning/phases/05-mvp-deployment/05-VALIDATION.md +@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md +@adapter/matrix/bot.py +@adapter/matrix/store.py +@adapter/matrix/handlers/auth.py +@tests/adapter/matrix/test_invite_space.py +@tests/adapter/matrix/test_chat_space.py +@tests/adapter/matrix/test_restart_persistence.py + + +From `adapter/matrix/bot.py`: + +```python +async def prepare_live_sync(client: AsyncClient) -> str | None: + response = await client.sync(timeout=0, full_state=True) + if isinstance(response, SyncResponse): + return response.next_batch + return None +``` + +```python +class MatrixBot: + async def _bootstrap_unregistered_room( + self, + room: MatrixRoom, + sender: str, + ) -> list[OutgoingEvent] | None: ... +``` + +From `adapter/matrix/store.py`: + +```python +async def get_room_meta(store: StateStore, room_id: str) -> dict | None: ... +async def set_room_meta(store: StateStore, room_id: str, meta: dict) -> None: ... +async def get_user_meta(store: StateStore, matrix_user_id: str) -> dict | None: ... +async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> None: ... +async def next_platform_chat_id(store: StateStore) -> str: ... +``` + + + + + + + Task 1: Add restart reconciliation regression coverage + tests/adapter/matrix/test_reconciliation.py, tests/adapter/matrix/test_restart_persistence.py + tests/adapter/matrix/test_invite_space.py, tests/adapter/matrix/test_chat_space.py, tests/adapter/matrix/test_restart_persistence.py, adapter/matrix/bot.py, adapter/matrix/handlers/auth.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md + + - Test 1: startup recovery rebuilds user space metadata, room metadata, and chat bindings from Matrix topology without creating new working rooms (per D-Phase05-reset and PH05-01). + - Test 2: reconciliation is idempotent and safe when local SQLite state is already present. + - Test 3: reconciliation happens before lazy `_bootstrap_unregistered_room()` would run for existing rooms (per PH05-03). + - Test 4: legacy room metadata missing `platform_chat_id` is backfilled deterministically at startup and persisted before routed handling begins. + + + - `tests/adapter/matrix/test_reconciliation.py` exists and names reconciliation entrypoints explicitly. + - The new tests assert restored `space_id`, `chat_id`, `matrix_user_id`, and `platform_chat_id` values for recovered rooms. + - The regression slice also proves existing Space onboarding behavior still passes by running `test_invite_space.py` and `test_chat_space.py`. + - The automated command in `` fails before implementation or would fail if reconciliation is removed. + + Create a dedicated `tests/adapter/matrix/test_reconciliation.py` module and extend restart persistence coverage so Phase 05 has a real Wave 0 contract. Model the recovered topology after the Phase 01 Space+rooms onboarding tests, not a DM-first flow, and explicitly keep those onboarding regressions in the verification slice so restart hardening cannot break provisioning UX. Cover recovery of `user_meta`, `room_meta`, `ChatManager` bindings, and room-local routing fields from Matrix-side state before live callbacks begin, including deterministic backfill for legacy rooms that predate `platform_chat_id`. Keep temporary UX state out of scope, per research. + + pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py -v + + Phase 05 has failing-or-red-before-code tests that define authoritative restart reconciliation behavior and exclude duplicate room provisioning. + + + + Task 2: Implement authoritative startup reconciliation and wire it before live sync + adapter/matrix/reconciliation.py, adapter/matrix/bot.py + adapter/matrix/bot.py, adapter/matrix/store.py, adapter/matrix/handlers/auth.py, tests/adapter/matrix/test_reconciliation.py, tests/adapter/matrix/test_restart_persistence.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md + + - Test 1: startup rebuild runs after login and initial full-state fetch, but before `sync_forever()` processes live events. + - Test 2: recovered rooms keep their existing Space+rooms identity and do not trigger `_bootstrap_unregistered_room()` unless the room is genuinely new. + - Test 3: local metadata can be rebuilt from Matrix topology when SQLite entries are missing, while existing valid metadata remains stable. + - Test 4: startup repair assigns a deterministic `platform_chat_id` to legacy rooms missing that field and persists it before routed platform calls can occur. + + + - `adapter/matrix/reconciliation.py` exports a focused reconciliation entrypoint used by startup code. + - `adapter/matrix/bot.py` invokes reconciliation before `client.sync_forever(...)`. + - Recovered room metadata includes `room_type`, `chat_id`, `space_id`, `matrix_user_id`, and `platform_chat_id` where available or rebuildable. + - Legacy rooms missing `platform_chat_id` follow one documented startup backfill path rather than ad hoc routing fallbacks. + + Implement a restart recovery module that treats Matrix topology as authoritative, per the Phase 05 reset and research notes. Rebuild missing local metadata for Space-owned working rooms, deterministically backfill missing `platform_chat_id` values for legacy rooms, and re-create `ChatManager` entries needed by routing, while keeping SQLite as a rebuildable cache rather than the source of truth. Wire the new reconciliation step into startup after the initial full-state sync and before live sync begins, and keep the onboarding regression slice green while doing it. Do not widen into timeline scraping, new storage backends, or DM-first fallbacks. + + pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v + + Restart recovery restores the minimum durable state for existing Space rooms before live traffic, and the guarded regression suite passes. + + + + + +Run the onboarding, reconciliation, restart-persistence, and Matrix dispatcher slices together. Confirm startup now has a deterministic pre-sync recovery and legacy-room backfill step instead of relying on lazy room bootstrap or routing-time fallbacks for existing topology. + + + +The bot can restart with partial or empty local room metadata, rebuild managed Space rooms before live sync, and continue handling those rooms without creating duplicate onboarding rooms. + + + +After completion, create `.planning/phases/05-mvp-deployment/05-01-SUMMARY.md` + diff --git a/.planning/phases/05-mvp-deployment/05-01-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-01-SUMMARY.md new file mode 100644 index 0000000..c50f371 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-01-SUMMARY.md @@ -0,0 +1,99 @@ +--- +phase: 05-mvp-deployment +plan: 01 +subsystem: infra +tags: [matrix, reconciliation, sqlite, startup, testing] +requires: + - phase: 01-matrix-mvp + provides: Space+rooms onboarding, room metadata, and Matrix dispatcher behavior + - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma + provides: durable platform_chat_id and restart persistence primitives +provides: + - authoritative startup reconciliation from Matrix room topology into local metadata + - pre-sync startup wiring that repairs managed rooms before live traffic + - restart regression coverage for reconciliation, idempotence, and legacy platform_chat_id backfill +affects: [matrix, startup, deployment, restart-persistence] +tech-stack: + added: [] + patterns: [matrix-topology-as-source-of-truth, sqlite-cache-rebuild, pre-sync-reconciliation] +key-files: + created: [adapter/matrix/reconciliation.py, tests/adapter/matrix/test_reconciliation.py] + modified: [adapter/matrix/bot.py, tests/adapter/matrix/test_restart_persistence.py] +key-decisions: + - "Treat synced Matrix parent/child topology as authoritative for managed room recovery; keep SQLite rebuildable." + - "Backfill missing platform_chat_id values during startup reconciliation instead of routing-time fallbacks." +patterns-established: + - "Startup runs full-state sync, then reconciliation, then sync_forever." + - "Recovered Matrix rooms rebuild user_meta, room_meta, auth state, and ChatManager bindings idempotently." +requirements-completed: [PH05-01, PH05-03] +duration: 8min +completed: 2026-04-27 +--- + +# Phase 05 Plan 01: Restart Reconciliation Summary + +**Matrix startup now rebuilds Space-owned working rooms into durable local routing state before live sync begins** + +## Performance + +- **Duration:** 8 min +- **Started:** 2026-04-27T22:00:47Z +- **Completed:** 2026-04-27T22:08:47Z +- **Tasks:** 2 +- **Files modified:** 4 + +## Accomplishments +- Added a dedicated reconciliation module that restores `user_meta`, `room_meta`, auth state, chat bindings, and missing `platform_chat_id` values from the synced Matrix room graph. +- Wired startup to run reconciliation immediately after the initial full-state sync and before `sync_forever()`. +- Added regression coverage for recovery, idempotence, pre-sync ordering, onboarding compatibility, and legacy restart backfill. + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Add restart reconciliation regression coverage** - `a75b26a` (test) +2. **Task 2: Implement authoritative startup reconciliation and wire it before live sync** - `8a80d00` (feat) + +## Files Created/Modified +- `adapter/matrix/reconciliation.py` - Startup recovery from Matrix topology into local room and user metadata. +- `adapter/matrix/bot.py` - Startup wiring that runs reconciliation after the bootstrap sync and before live sync. +- `tests/adapter/matrix/test_reconciliation.py` - Recovery, idempotence, and startup-order regression coverage. +- `tests/adapter/matrix/test_restart_persistence.py` - Legacy `platform_chat_id` backfill persistence coverage. + +## Decisions Made +- Used the synced Matrix room graph as the authoritative source for restart recovery, while preserving existing local metadata whenever it is already valid. +- Kept legacy `platform_chat_id` repair on a single startup path so routed handling never needs ad hoc fallback creation for existing rooms. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Switched verification to a clean `uv run pytest` environment** +- **Found during:** Task 1 and Task 2 verification +- **Issue:** The default `pytest` path used a mismatched virtualenv without repo dependencies, and `.env` injected Matrix backend variables that polluted mock-mode tests. +- **Fix:** Ran the verification slice through `uv run pytest` with `UV_CACHE_DIR=/tmp/uv-cache-surfaces` and blank `MATRIX_AGENT_REGISTRY_PATH` / `MATRIX_PLATFORM_BACKEND` values to match the intended test environment. +- **Files modified:** None +- **Verification:** `uv run pytest` slice passed with 50/50 tests green +- **Committed in:** not applicable (verification-only adjustment) + +--- + +**Total deviations:** 1 auto-fixed (1 blocking) +**Impact on plan:** Verification needed an environment correction, but code scope stayed within the plan and owned files. + +## Issues Encountered +- The shell environment loaded deployment-oriented Matrix backend settings from `.env`; these had to be neutralized for the mock-mode regression slice. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Restart recovery is in place for existing Space rooms, including deterministic legacy `platform_chat_id` repair. +- Remaining Phase 05 plans can build on a stable pre-sync recovery path instead of lazy bootstrap for existing topology. + +## Self-Check: PASSED + +--- +*Phase: 05-mvp-deployment* +*Completed: 2026-04-27* diff --git a/.planning/phases/05-mvp-deployment/05-02-PLAN.md b/.planning/phases/05-mvp-deployment/05-02-PLAN.md new file mode 100644 index 0000000..dc93cf0 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-02-PLAN.md @@ -0,0 +1,156 @@ +--- +phase: 05-mvp-deployment +plan: 02 +type: execute +wave: 2 +depends_on: + - 05-01 +files_modified: + - adapter/matrix/handlers/__init__.py + - adapter/matrix/handlers/context_commands.py + - adapter/matrix/routed_platform.py + - tests/adapter/matrix/test_context_commands.py + - tests/adapter/matrix/test_routed_platform.py +autonomous: true +requirements: + - PH05-02 +must_haves: + truths: + - "Each working Matrix room uses its own durable `platform_chat_id` as the real agent context boundary." + - "`!clear` resets only the current room by rotating its `platform_chat_id` and disconnecting the old upstream chat." + - "Save, load, context, and routed send paths resolve through room-local platform context, not shared user state." + - "Strict room routing assumes startup reconciliation has already repaired legacy rooms missing `platform_chat_id`." + artifacts: + - path: "adapter/matrix/handlers/context_commands.py" + provides: "Room-local `!clear`, save/load/context resolution, and upstream disconnect behavior" + - path: "adapter/matrix/routed_platform.py" + provides: "Strict room -> agent_id + platform_chat_id routing" + - path: "tests/adapter/matrix/test_context_commands.py" + provides: "Regression coverage for `!clear` and room-local context commands" + key_links: + - from: "adapter/matrix/handlers/__init__.py" + to: "adapter/matrix/handlers/context_commands.py" + via: "IncomingCommand registration for `clear`" + pattern: "\"clear\"" + - from: "adapter/matrix/routed_platform.py" + to: "adapter/matrix/store.py" + via: "room metadata lookup" + pattern: "platform_chat_id" +--- + + +Make room-local platform context explicit and user-facing by shipping real `!clear` semantics and strict per-room routing. + +Purpose: Phase 05 must preserve Space+rooms UX while giving each room a true upstream context boundary. +Output: Updated command wiring, room-local context reset behavior, and routing regressions tied to `platform_chat_id`. + + + +@/Users/a/.codex/get-shit-done/workflows/execute-plan.md +@/Users/a/.codex/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/05-mvp-deployment/05-RESEARCH.md +@.planning/phases/05-mvp-deployment/05-VALIDATION.md +@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md +@adapter/matrix/handlers/__init__.py +@adapter/matrix/handlers/context_commands.py +@adapter/matrix/routed_platform.py +@tests/adapter/matrix/test_context_commands.py +@tests/adapter/matrix/test_routed_platform.py + + +From `adapter/matrix/handlers/__init__.py`: + +```python +dispatcher.register( + IncomingCommand, + "reset", + make_handle_reset(store, prototype_state) + if prototype_state is not None + else handle_settings, +) +``` + +From `adapter/matrix/handlers/context_commands.py`: + +```python +async def _resolve_context_scope( + event: IncomingCommand, + store: StateStore, + chat_mgr, +) -> tuple[str, str | None]: ... +``` + +From `adapter/matrix/routed_platform.py`: + +```python +async def _resolve_delegate(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]: + ... +``` + + + + + + + Task 1: Expand room-local context and clear-command tests + tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py + tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py, adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py, .planning/phases/05-mvp-deployment/05-VALIDATION.md + + - Test 1: `!clear` rotates only the current room's `platform_chat_id` and disconnects only the old upstream chat (per PH05-02). + - Test 2: `!clear` is the supported command name; `!reset` may remain as a compatibility alias but must not be the only registered path. + - Test 3: routed send/stream paths fail fast when room metadata lacks `agent_id` or `platform_chat_id` instead of silently sharing context. + - Test 4: routed behavior uses startup-repaired room metadata and does not introduce a second fallback path that invents `platform_chat_id` during message handling. + + + - Tests explicitly mention `clear` in command registration or command invocation. + - The context-command tests assert old and new `platform_chat_id` values and upstream disconnect behavior. + - The routed-platform tests assert room-local IDs are passed to delegates unchanged. + + Extend the current Matrix context-command and routed-platform regressions so Phase 05 has direct coverage for `!clear`, room-local `platform_chat_id` rotation, and fail-fast routing when room bindings are incomplete. Treat startup reconciliation from `05-01` as the only supported repair path for legacy rooms missing `platform_chat_id`; the routed path must consume repaired metadata, not synthesize new room identities on demand. Preserve the Phase 04 prototype-state behavior where it still fits, but anchor new checks on per-room context isolation rather than shared session assumptions. + + pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py -v + + The tests define the Phase 05 room-local contract for reset/clear and for routed upstream calls. + + + + Task 2: Ship real room-local `!clear` semantics and strict routing + adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py + adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py, tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md + + - Test 1: command registration exposes `!clear` as the real context-reset entrypoint for Matrix rooms. + - Test 2: only the active room's `platform_chat_id` rotates, and only the old upstream chat session is disconnected. + - Test 3: all room-local context commands resolve through recovered room metadata instead of falling back to shared user scope. + - Test 4: strict routing stays strict at runtime because legacy-room repair was already handled at startup by `05-01`, not by hidden message-path fallbacks. + + + - `adapter/matrix/handlers/__init__.py` registers `clear`; if `reset` remains, it is clearly a compatibility alias. + - `adapter/matrix/handlers/context_commands.py` resolves and rotates room-local platform context without touching other rooms. + - `adapter/matrix/routed_platform.py` keeps explicit `MATRIX_ROUTE_INCOMPLETE` behavior when bindings are missing. + + Update the Matrix context command surface to match the Phase 05 contract: real `!clear`, room-local `platform_chat_id` rotation, and upstream disconnect scoped to the old room context. Keep `save`, `load`, and `context` anchored to the same room-local identity. Tighten routed-platform behavior only where needed to preserve fail-fast semantics after startup reconciliation has repaired legacy rooms; do not reintroduce shared chat state, user-level reset behavior, or message-time backfill of missing `platform_chat_id`. + + pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v + + Users can clear one working room without affecting others, and all routed upstream calls stay bound to room-local platform context. + + + + + +Run the context and routed-platform slices plus Matrix dispatcher smoke coverage to confirm the exposed command name and room-local routing behavior are consistent. + + + +Every working Matrix room has an independent upstream context boundary, and `!clear` resets only the room where it is invoked. + + + +After completion, create `.planning/phases/05-mvp-deployment/05-02-SUMMARY.md` + diff --git a/.planning/phases/05-mvp-deployment/05-03-PLAN.md b/.planning/phases/05-mvp-deployment/05-03-PLAN.md new file mode 100644 index 0000000..01023b3 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-03-PLAN.md @@ -0,0 +1,145 @@ +--- +phase: 05-mvp-deployment +plan: 03 +type: execute +wave: 1 +depends_on: [] +files_modified: + - adapter/matrix/files.py + - sdk/real.py + - tests/adapter/matrix/test_files.py + - tests/platform/test_real.py +autonomous: true +requirements: + - PH05-04 +must_haves: + truths: + - "Incoming Matrix attachments are written into a room-safe shared-volume path and passed upstream as relative workspace paths." + - "Agent-emitted files can be returned to Matrix users without inventing a separate file proxy." + - "The shared-volume contract works with the Phase 05 `/agents` deployment shape." + artifacts: + - path: "adapter/matrix/files.py" + provides: "Room-safe shared-volume path building and path resolution" + - path: "sdk/real.py" + provides: "Attachment path passthrough and send-file normalization" + - path: "tests/adapter/matrix/test_files.py" + provides: "Regression coverage for shared-volume path construction" + key_links: + - from: "adapter/matrix/files.py" + to: "sdk/real.py" + via: "relative `workspace_path` transport" + pattern: "workspace_path" + - from: "sdk/real.py" + to: "adapter/matrix/bot.py" + via: "OutgoingMessage attachments rendered back to Matrix" + pattern: "MsgEventSendFile" +--- + + +Harden the Matrix attachment path contract around the shared deployment volume instead of custom transport shims. + +Purpose: Phase 05 file handling must survive real deployment with room-safe paths and outbound file delivery through the existing shared-volume model. +Output: Attachment-path regressions and any targeted runtime fixes needed for `/agents`-backed shared volume behavior. + + + +@/Users/a/.codex/get-shit-done/workflows/execute-plan.md +@/Users/a/.codex/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/05-mvp-deployment/05-RESEARCH.md +@.planning/phases/05-mvp-deployment/05-VALIDATION.md +@docs/deploy-architecture.md +@docs/superpowers/specs/2026-04-20-matrix-shared-workspace-file-flow-design.md +@adapter/matrix/files.py +@sdk/real.py +@tests/adapter/matrix/test_files.py +@tests/platform/test_real.py + + +From `adapter/matrix/files.py`: + +```python +def build_workspace_attachment_path( + *, + workspace_root: Path, + matrix_user_id: str, + room_id: str, + filename: str, + timestamp: str | None = None, +) -> tuple[str, Path]: ... +``` + +From `sdk/real.py`: + +```python +@staticmethod +def _attachment_paths(attachments: list[Attachment] | None) -> list[str]: ... + +@staticmethod +def _attachment_from_send_file_event(event: MsgEventSendFile) -> Attachment: ... +``` + + + + + + + Task 1: Add shared-volume file contract tests for `/agents` deployment + tests/adapter/matrix/test_files.py, tests/platform/test_real.py + tests/adapter/matrix/test_files.py, tests/platform/test_real.py, adapter/matrix/files.py, sdk/real.py, docs/deploy-architecture.md, .planning/phases/05-mvp-deployment/05-RESEARCH.md + + - Test 1: incoming Matrix files land under a room-safe `surfaces/matrix/.../inbox/...` path that remains relative to the agent workspace contract. + - Test 2: upstream file events normalize `/workspace/...` and `/agents/...`-style absolute paths into relative `workspace_path` values. + - Test 3: attachment forwarding never switches to inline blobs or HTTP shim URLs (per PH05-04). + + + - `tests/adapter/matrix/test_files.py` asserts the path namespace includes sanitized user and room components. + - `tests/platform/test_real.py` contains explicit coverage for send-file path normalization. + - The automated test command in `` exercises both inbound and outbound sides of the shared-volume contract. + + Expand the file-flow regressions around the real deployment contract described in research and `docs/deploy-architecture.md`. Keep the tests centered on relative `workspace_path` transport and room-safe on-disk layout. Do not introduce proxy URLs, base64 payload transport, or new platform endpoints. + + pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v + + Phase 05 has direct test coverage for `/agents`-backed shared-volume behavior across inbound and outbound file paths. + + + + Task 2: Tighten attachment path handling for the shared volume contract + adapter/matrix/files.py, sdk/real.py + adapter/matrix/files.py, sdk/real.py, tests/adapter/matrix/test_files.py, tests/platform/test_real.py, docs/deploy-architecture.md + + - Test 1: inbound attachment helpers keep returning relative paths even when the bot writes into `/agents`. + - Test 2: outbound file normalization accepts absolute paths from the agent runtime but strips them back to relative workspace paths for Matrix rendering. + - Test 3: no code path emits non-relative attachment references to the upstream agent API. + + + - `sdk/real.py` only forwards relative attachment paths to the agent API. + - `sdk/real.py` normalizes both `/workspace` and `/agents` absolute roots if present in send-file events. + - `adapter/matrix/files.py` remains the single source of truth for room-safe attachment path construction. + + Implement only the minimum runtime changes needed to satisfy the shared-volume tests. Keep `adapter/matrix/files.py` as the single place that builds surface-owned attachment paths, and keep `sdk/real.py` responsible only for attachment passthrough and send-file normalization. Do not widen this plan into compose edits, registry redesign, or bot command changes. + + pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v + + Incoming and outgoing file references stay compatible with the real shared-volume deployment contract, and the targeted file/path regressions pass. + + + + + +Run the Matrix file helper, real platform client, and outgoing-send slices together so the shared-volume contract is validated from write path through return-to-user rendering. + + + +The Matrix bot and agent runtime can exchange file references through the shared volume using only relative workspace paths and room-safe storage layout. + + + +After completion, create `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md` + diff --git a/.planning/phases/05-mvp-deployment/05-04-PLAN.md b/.planning/phases/05-mvp-deployment/05-04-PLAN.md new file mode 100644 index 0000000..4fe2235 --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-04-PLAN.md @@ -0,0 +1,128 @@ +--- +phase: 05-mvp-deployment +plan: 04 +type: execute +wave: 2 +depends_on: + - 05-03 +files_modified: + - docker-compose.prod.yml + - docker-compose.fullstack.yml + - Dockerfile + - .env.example + - README.md + - docs/deploy-architecture.md +autonomous: true +requirements: + - PH05-05 +must_haves: + truths: + - "Production handoff uses a bot-only compose artifact instead of the internal full-stack harness." + - "Internal E2E compose brings up the bot, platform-agent, and shared volume with explicit health-gated startup." + - "Deployment docs and env examples match the split compose artifacts and shared `/agents` contract." + artifacts: + - path: "docker-compose.prod.yml" + provides: "Bot-only deployment handoff artifact" + - path: "docker-compose.fullstack.yml" + provides: "Internal E2E harness with shared volume and dependency gating" + - path: ".env.example" + provides: "Documented runtime contract for Phase 05 deployment" + key_links: + - from: "docker-compose.fullstack.yml" + to: "docker-compose.prod.yml" + via: "shared service definition or explicit duplication" + pattern: "matrix-bot" + - from: "docs/deploy-architecture.md" + to: "docker-compose.prod.yml" + via: "operator handoff instructions" + pattern: "prod" +--- + + +Split deployment artifacts by operational intent so operator handoff and internal E2E testing stop sharing the same compose contract. + +Purpose: Phase 05 needs an explicit bot-only production artifact and a separate full-stack compose harness aligned with the shared-volume design. +Output: `docker-compose.prod.yml`, `docker-compose.fullstack.yml`, and updated env/docs describing when to use each. + + + +@/Users/a/.codex/get-shit-done/workflows/execute-plan.md +@/Users/a/.codex/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/05-mvp-deployment/05-RESEARCH.md +@.planning/phases/05-mvp-deployment/05-VALIDATION.md +@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md +@docs/deploy-architecture.md +@docker-compose.yml +@Dockerfile +@.env.example + + +Current root compose contract: + +```yaml +services: + platform-agent: + ... + matrix-bot: + build: . + env_file: .env + environment: + AGENT_BASE_URL: http://platform-agent:8000 + SURFACES_WORKSPACE_DIR: /workspace +``` + + + + + + + Task 1: Create split prod and fullstack compose artifacts + docker-compose.prod.yml, docker-compose.fullstack.yml, Dockerfile, .env.example + docker-compose.yml, Dockerfile, .env.example, docs/deploy-architecture.md, .planning/phases/05-mvp-deployment/05-RESEARCH.md, .planning/phases/05-mvp-deployment/05-VALIDATION.md + + - `docker-compose.prod.yml` defines only the bot-side runtime required for operator handoff. + - `docker-compose.fullstack.yml` includes the internal platform-agent service, shared volume mounts, and health-gated startup rather than sleep-based sequencing. + - `.env.example` documents the Phase 05 env contract without requiring the reader to inspect the old root compose file. + + Create two explicit compose artifacts per PH05-05: a bot-only `docker-compose.prod.yml` for deployment handoff and a `docker-compose.fullstack.yml` for internal E2E runs. Align mounts and env values with the Phase 05 shared `/agents` volume direction from research. Reuse the existing Dockerfile unless a small compatibility edit is required. Do not keep the old single-file compose setup as the only documented runtime. + + docker compose -f docker-compose.prod.yml config > /tmp/phase05-prod-compose.yml && docker compose -f docker-compose.fullstack.yml config > /tmp/phase05-fullstack-compose.yml && rg -n "^services:$|^ matrix-bot:$|^volumes:$|/agents" /tmp/phase05-prod-compose.yml && test -z "$(rg -n "^ platform-agent:$" /tmp/phase05-prod-compose.yml)" && rg -n "^ matrix-bot:$|^ platform-agent:$|condition: service_healthy|healthcheck:|/agents" /tmp/phase05-fullstack-compose.yml + + Both compose files render successfully and express distinct operational roles: prod handoff vs internal full-stack testing. + + + + Task 2: Update deployment docs and operator guidance for the split artifacts + README.md, docs/deploy-architecture.md + README.md, docs/deploy-architecture.md, docker-compose.prod.yml, docker-compose.fullstack.yml, .env.example + + - README or deploy doc tells the operator exactly which compose file to use for production vs internal E2E. + - The docs describe the shared `/agents` volume behavior and reference the relevant env vars. + - The old root `docker-compose.yml` is no longer the primary documented deployment path. + + Update the repo docs so the Phase 05 deployment story is executable without inference: production handoff stays bot-only, full-stack compose is for internal E2E, and shared-volume file behavior is described in the same terms as the runtime artifacts. Keep documentation narrowly scoped to the shipped compose split; do not widen into platform-master or future storage design. + + rg -n "docker-compose\\.prod|docker-compose\\.fullstack|/agents|prod handoff|full-stack" README.md docs/deploy-architecture.md .env.example && rg -n "production|deploy" README.md docs/deploy-architecture.md | rg "docker-compose\\.prod" && test -z "$(rg -n "docker compose up|docker-compose\\.yml" README.md docs/deploy-architecture.md | rg "production|deploy")" + + The docs and env guidance match the new compose artifacts and no longer imply a single shared deployment file. + + + + + +Render both compose files, then grep the docs for the new artifact names and `/agents` references so the operator contract is explicit and consistent. + + + +An operator can deploy the Matrix bot with the bot-only compose file, while developers can run the internal end-to-end harness separately without reinterpreting the deployment docs. + + + +After completion, create `.planning/phases/05-mvp-deployment/05-04-SUMMARY.md` + diff --git a/.planning/phases/05-mvp-deployment/05-CONTEXT.md b/.planning/phases/05-mvp-deployment/05-CONTEXT.md deleted file mode 100644 index 553d7f5..0000000 --- a/.planning/phases/05-mvp-deployment/05-CONTEXT.md +++ /dev/null @@ -1,157 +0,0 @@ -# Phase 05: MVP Deployment — Context - -**Gathered:** 2026-04-27 -**Status:** Ready for planning - - -## Phase Boundary - -Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru: -1. Перейти на single-chat архитектуру (chat_id=0, один контекст на пользователя) -2. Упростить онбординг: DM-first без Space/rooms provisioning, welcome-сообщение при invite -3. Расширить config/matrix-agents.yaml — добавить user_agents (Matrix user_id → agent_id) и per-agent base_url/workspace_path -4. Обновить AgentRegistry и _build_platform_from_env для per-agent URL routing -5. Реализовать file transfer через shared volume /agents/: входящие → incoming/{filename}, исходящие через MsgEventSendFile -6. Добавить !clear (сброс контекста через переподключение AgentApi) -7. Написать docker-compose.prod.yml с полным стеком (matrix-bot + placeholder agent + named volume agents) -8. Удалить legacy: !agent, !new, !archive, !rename, !save, !load, Space-creation, C1/C2/C3 room provisioning - -НЕ входит: -- Конфигурация агентских контейнеров (платформа) -- Telegram-адаптер -- E2EE -- platform-master интеграция -- !save / !load (ненадёжны без persistent memory в агенте) - - - - -## Implementation Decisions - -### Single-chat архитектура -- **D-01:** chat_id=0 для всех сообщений. Один контекст агента на пользователя. Изоляции между разными разговорами нет — вместо этого `!clear` сбрасывает контекст. -- **D-02:** Удалить всю multi-room инфраструктуру: C1/C2/C3, `!new`, `!archive`, `!rename`, Space-creation, room provisioning. Matrix-бот работает только в DM-комнате (личка с ботом). -- **D-03:** Удалить `!save` и `!load` — ненадёжны без persistent memory в агенте (MemorySaver сбрасывается на рестарте). - -### Онбординг (DM-first) -- **D-04:** При получении invite в DM-комнату — принять, отправить welcome-сообщение: "Привет! Я Lambda AI-агент. Просто напиши — и я отвечу. `!clear` чтобы начать новый разговор, `!context` чтобы посмотреть статус." -- **D-05:** Никакого Space, никаких дочерних комнат. Вся переписка в одной DM-комнате. - -### !clear (новая команда) -- **D-06:** Сбросить контекст агента — закрыть текущий AgentApi connection и создать новый (`await agent.close()` + `await agent.connect()`). Это сбрасывает MemorySaver. Подтвердить пользователю: "Контекст сброшен. Начнём с чистого листа." - -### !agent команда -- **D-07:** Удалить полностью. Маппинг user→agent теперь статический из config. Пользователь не может менять агента. - -### Конфиг агентов (config/matrix-agents.yaml) -- **D-02:** Расширить текущий matrix-agents.yaml — добавить user_agents dict и поля base_url/workspace_path к каждому агенту. Один файл, один парсер. Формат по docs/deploy-architecture.md: - ```yaml - user_agents: - "@user0:matrix.lambda.coredump.ru": agent-0 - "@user1:matrix.lambda.coredump.ru": agent-1 - - agents: - - id: agent-0 - label: "Agent 0" - base_url: "ws://lambda.coredump.ru:7000/agent_0/" - workspace_path: "/agents/0/" - ``` -- **D-03:** AgentDefinition расширяется полями base_url (str) и workspace_path (str). AgentRegistry добавляет user_agents dict (Matrix user_id → agent_id) и метод get_agent_id_by_user(matrix_user_id). - -### Роутинг user → agent в _build_platform_from_env -- **D-04:** Вместо глобального AGENT_BASE_URL — per-agent URL из конфига. _build_platform_from_env строит delegates с правильным base_url для каждого агента. RoutedPlatformClient._resolve_delegate использует user_agents из registry для определения delegate по Matrix user_id. - -### Входящие файлы (пользователь → агент) -- **D-05:** Путь внутри workspace агента: `incoming/{filename}`. Абсолютный путь: `{workspace_path}/incoming/{filename}` (например `/agents/0/incoming/photo.jpg`). Обновить files.py: `build_workspace_attachment_path` принимает workspace_path агента и строит путь `incoming/{filename}`. Передавать в agent.send_message() как attachments=["incoming/{filename}"] (относительно /workspace). -- **D-06:** workspace_path агента берётся из AgentDefinition по agent_id пользователя. - -### Исходящие файлы (агент → пользователь) -- **D-07:** При получении MsgEventSendFile(path="output/report.pdf") — читать файл из `{workspace_path}/{path}`. Отправлять как Matrix file message. Обработчик в Matrix bot.py при обработке stream-ответов от агента. - -### docker-compose для prod -- **D-08:** `docker-compose.prod.yml` включает полный стек: Matrix-бот + агент-контейнер (placeholder image `lambda-agent:latest` — уточнить у платформы) + named volume `agents`. Это позволяет тестировать полный стек самостоятельно. Платформа берёт отсюда схему интеграции для своего деплоя. -- **D-09:** Named volume `agents` монтируется в Matrix-бот как `/agents/` и в агент-контейнер как `/workspace`. Env vars из `.env.prod`. Запуск: `docker compose -f docker-compose.prod.yml up`. - -### Неавторизованные пользователи -- **D-10:** Если Matrix user_id не найден в `user_agents` — принять invite, отправить сообщение: "К вашему аккаунту не привязан агент. Напишите @og_mput в Telegram для получения доступа." Дальнейшие сообщения игнорировать (или повторять то же сообщение). - -### !clear -- **D-11:** Без диалога подтверждения — сбрасывает немедленно. Закрыть текущий AgentApi connection, создать новый. Ответ пользователю: "Контекст сброшен." - -### !settings и прочие команды настроек -- **D-12:** Удалить `!settings`, `!settings soul`, `!settings skills`, `!settings safety` — agent_api не предоставляет настроек, всё равно возвращало "недоступно в MVP". - -### Claude's Discretion -- MATRIX_AGENT_REGISTRY_PATH — оставить как env var для пути к конфигу (уже существует) -- Формат .env.prod -- Group room invites (не-DM) — отклонять автоматически -- Существующие Space+rooms у старых пользователей — игнорировать, не мигрировать - - - - -## Canonical References - -**Downstream agents MUST read these before planning or implementing.** - -### Deployment architecture (PRIMARY) -- `docs/deploy-architecture.md` — Топология, формат конфига, AgentApi lifecycle, file transfer protocol, открытые вопросы - -### Существующий код (изменяем) -- `adapter/matrix/agent_registry.py` — AgentRegistry, AgentDefinition, load_agent_registry — расширяем -- `adapter/matrix/bot.py` — _build_platform_from_env, _load_agent_registry_from_env — обновляем роутинг -- `adapter/matrix/routed_platform.py` — RoutedPlatformClient._resolve_delegate — обновляем логику -- `adapter/matrix/files.py` — build_workspace_attachment_path, download_matrix_attachment — меняем путь -- `adapter/matrix/handlers/agent.py` — удаляем или делаем no-op (!agent handler) -- `config/matrix-agents.yaml` — расширяем формат -- `docker-compose.yml` — существующий dev compose (за основу для prod варианта) - -### SDK (используем как есть) -- `sdk/real.py` — RealPlatformClient — base_url теперь per-instance, но сам класс не меняется -- `sdk/upstream_agent_api.py` — AgentApi, MsgEventSendFile — читаем MsgEventSendFile в стриме - - - - -## Existing Code Insights - -### Reusable Assets -- `adapter/matrix/files.py::build_workspace_attachment_path` — уже строит путь к файлу, нужно заменить логику `surfaces/matrix/...` на `incoming/{filename}` -- `adapter/matrix/files.py::download_matrix_attachment` — скачивает файл, нужно передавать workspace_path агента -- `adapter/matrix/agent_registry.py::load_agent_registry` — парсер YAML, расширяем без переписывания - -### Established Patterns -- `RoutedPlatformClient` + delegates: dict[agent_id, RealPlatformClient] — паттерн уже есть, нужно только per-agent URL при создании delegates -- `MATRIX_PLATFORM_BACKEND=real` активирует prod-path — сохраняем -- `MATRIX_AGENT_REGISTRY_PATH` — env var для пути к конфигу — сохраняем - -### Integration Points -- `_build_platform_from_env` создаёт delegates — здесь меняется источник URL (из конфига, не из env) -- `RoutedPlatformClient._resolve_delegate` — здесь добавляется lookup по user_agents -- Matrix bot stream handler — здесь добавляется обработка MsgEventSendFile - - - - -## Specific Ideas - -- AgentApi конструктор в master ветке: `AgentApi(agent_id, base_url, on_disconnect=..., chat_id=0)` — base_url это ws:// URL агента -- Входящий файл: bot скачивает из Matrix → пишет в `{workspace_path}/incoming/{filename}` → вызывает `agent.send_message(text, attachments=["incoming/{filename}"])` (путь relative to /workspace) -- Исходящий файл: при `MsgEventSendFile(path="output/report.pdf")` → читаем `{workspace_path}/output/report.pdf` → отправляем в Matrix через `client.upload()` → `client.room_send(m.file)` -- docker-compose.prod.yml монтирует volume: `volumes: ["/agents/:/agents/"]` — хост обеспечивает директорию - - - - -## Deferred Ideas - -- platform-master интеграция (динамический get_agent_url через POST /api/v1/create) — когда feat/storage будет готов -- !agent как admin-override — не нужен для MVP, можно добавить позже если потребуется -- Per-chat context isolation через разные chat_id (сейчас chat_id=0 для всех) — ждём platform сигнал - - - ---- - -*Phase: 05-mvp-deployment* -*Context gathered: 2026-04-27* diff --git a/.planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md b/.planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md deleted file mode 100644 index 1e30b8c..0000000 --- a/.planning/phases/05-mvp-deployment/05-DISCUSSION-LOG.md +++ /dev/null @@ -1,65 +0,0 @@ -# Phase 05: MVP Deployment — Discussion Log - -> **Audit trail only.** Do not use as input to planning, research, or execution agents. -> Decisions captured in CONTEXT.md — this log preserves the alternatives considered. - -**Date:** 2026-04-27 -**Phase:** 05-mvp-deployment -**Areas discussed:** !agent legacy, file transfer path, config format, docker-compose scope - ---- - -## !agent команда - -| Option | Description | Selected | -|--------|-------------|----------| -| Удалить | Убираем полностью — маппинг статический из конфига | ✓ | -| Оставить как no-op | Команда остаётся но ничего не делает | | -| Только для dev-режима | Работает когда нет user_agents в конфиге | | - -**User's choice:** Удалить -**Notes:** Команда была legacy от эпохи когда роутинг был динамическим. С user_agents в конфиге она не нужна. - ---- - -## Путь входящих файлов - -| Option | Description | Selected | -|--------|-------------|----------| -| incoming/{filename} | По docs/deploy-architecture.md — /agents/N/incoming/file | ✓ | -| surfaces/matrix/{user}/{room}/inbox/{file} | Текущий формат files.py | | - -**User's choice:** incoming/{filename} -**Notes:** Пользователь указал — это решение от платформенной команды, зафиксировано в docs/deploy-architecture.md. - ---- - -## Формат config/matrix-agents.yaml - -| Option | Description | Selected | -|--------|-------------|----------| -| Расширить текущий YAML | Добавить user_agents + base_url/workspace_path в тот же файл | ✓ | -| Отдельный prod-config.yaml | Два файла: registry (id/label) + prod конфиг (URL/user_agents) | | - -**User's choice:** Расширить текущий YAML -**Notes:** Один файл проще. Формат уже определён в docs/deploy-architecture.md. - ---- - -## docker-compose prod scope - -**User's choice:** docker-compose.prod.yml только для Matrix-бота -**Notes:** Платформа отвечает за агентские контейнеры — мы их не трогаем. Matrix-бот монтирует /agents/ как external host path, платформа обеспечивает содержимое. - ---- - -## Claude's Discretion - -- Обработка Matrix user_id не найденного в user_agents -- Имена env переменных для prod -- Формат .env.prod - -## Deferred Ideas - -- platform-master интеграция -- Per-chat chat_id isolation diff --git a/.planning/phases/05-mvp-deployment/05-VALIDATION.md b/.planning/phases/05-mvp-deployment/05-VALIDATION.md index abe4bcb..6466df9 100644 --- a/.planning/phases/05-mvp-deployment/05-VALIDATION.md +++ b/.planning/phases/05-mvp-deployment/05-VALIDATION.md @@ -1,13 +1,13 @@ --- -phase: 5 +phase: 05 slug: mvp-deployment -status: draft -nyquist_compliant: false +status: revised +nyquist_compliant: true wave_0_complete: false -created: 2026-04-27 +created: 2026-04-28 --- -# Phase 5 — Validation Strategy +# Phase 05 — Validation Strategy > Per-phase validation contract for feedback sampling during execution. @@ -17,35 +17,35 @@ created: 2026-04-27 | Property | Value | |----------|-------| -| **Framework** | pytest | -| **Config file** | pyproject.toml | -| **Quick run command** | `pytest tests/adapter/matrix/ -v -x` | +| **Framework** | `pytest` + `pytest-asyncio` | +| **Config file** | `pyproject.toml` | +| **Quick run command** | `pytest tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py -v` | | **Full suite command** | `pytest tests/ -v` | -| **Estimated runtime** | ~30 seconds | +| **Estimated runtime** | targeted slices < 60 seconds each; full suite longer | --- ## Sampling Rate -- **After every task commit:** Run `pytest tests/adapter/matrix/ -v -x` -- **After every plan wave:** Run `pytest tests/ -v` -- **Before `/gsd-verify-work`:** Full suite must be green -- **Max feedback latency:** 30 seconds +- **After every task commit:** Run the exact `` command from the task that just changed +- **After every plan wave:** Run `pytest tests/adapter/matrix/ -v` +- **Before `$gsd-verify-work`:** Full suite must be green +- **Max feedback latency:** 60 seconds for task-level slices --- ## Per-Task Verification Map -| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status | -|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------| -| 05-A-01 | A | 1 | D-02/D-03 | — | agent_id lookup by matrix_user_id only | unit | `pytest tests/adapter/matrix/test_agent_registry.py -v` | ❌ W0 | ⬜ pending | -| 05-A-02 | A | 1 | D-04 | — | per-agent URL used in delegates | unit | `pytest tests/adapter/matrix/test_routed_platform.py -v` | ❌ W0 | ⬜ pending | -| 05-B-01 | B | 1 | D-04/D-05 | — | welcome message sent on invite | unit | `pytest tests/adapter/matrix/test_onboarding.py -v` | ❌ W0 | ⬜ pending | -| 05-B-02 | B | 1 | D-10 | — | unauthorized user gets access-denied message | unit | `pytest tests/adapter/matrix/test_onboarding.py::test_unauthorized -v` | ❌ W0 | ⬜ pending | -| 05-B-03 | B | 1 | D-11 | — | !clear closes and reopens AgentApi | unit | `pytest tests/adapter/matrix/test_commands.py::test_clear -v` | ❌ W0 | ⬜ pending | -| 05-C-01 | C | 2 | D-05/D-06 | — | incoming file written to workspace_path/incoming/ | unit | `pytest tests/adapter/matrix/test_files.py -v` | ✅ | ⬜ pending | -| 05-C-02 | C | 2 | D-07 | — | outgoing MsgEventSendFile reads from workspace_path | unit | `pytest tests/adapter/matrix/test_files.py::test_outgoing_file -v` | ❌ W0 | ⬜ pending | -| 05-C-03 | C | 2 | D-08/D-09 | — | docker-compose.prod.yml has agents volume and both services | manual | see below | N/A | ⬜ pending | +| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|-----------|-------------------|-------------|--------| +| 05-01-01 | 01 | 1 | PH05-01 | integration | `pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py -v` | ❌ W0 | ⬜ pending | +| 05-01-02 | 01 | 1 | PH05-03 | integration | `pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v` | ❌ W0 | ⬜ pending | +| 05-02-01 | 02 | 2 | PH05-02 | integration | `pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py -v` | ✅ partial | ⬜ pending | +| 05-02-02 | 02 | 2 | PH05-02 | integration | `pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v` | ✅ partial | ⬜ pending | +| 05-03-01 | 03 | 1 | PH05-04 | integration | `pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py -v` | ✅ partial | ⬜ pending | +| 05-03-02 | 03 | 1 | PH05-04 | integration | `pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v` | ✅ partial | ⬜ pending | +| 05-04-01 | 04 | 2 | PH05-05 | smoke | `docker compose -f docker-compose.prod.yml config && docker compose -f docker-compose.fullstack.yml config` | ❌ W0 | ⬜ pending | +| 05-04-02 | 04 | 2 | PH05-05 | docs smoke | `rg -n "docker-compose\\.prod|docker-compose\\.fullstack|/agents|prod handoff|full-stack" README.md docs/deploy-architecture.md .env.example` | ✅ | ⬜ pending | *Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* @@ -53,13 +53,11 @@ created: 2026-04-27 ## Wave 0 Requirements -- [ ] `tests/adapter/matrix/test_agent_registry.py` — tests for user_agents lookup and per-agent base_url/workspace_path -- [ ] `tests/adapter/matrix/test_routed_platform.py` — updated tests for _resolve_delegate using user_agents -- [ ] `tests/adapter/matrix/test_onboarding.py` — tests for invite handling, welcome message, unauthorized user response -- [ ] `tests/adapter/matrix/test_commands.py` — tests for !clear command behavior -- [ ] Update `tests/adapter/matrix/test_files.py` — add outgoing file test - -*Existing: `tests/adapter/matrix/test_files.py` — already exists, covers incoming file path logic* +- [ ] `tests/adapter/matrix/test_reconciliation.py` — startup recovery of user and room metadata from Matrix state +- [ ] `tests/adapter/matrix/test_restart_persistence.py` additions — deterministic backfill for legacy rooms missing `platform_chat_id` +- [ ] `tests/adapter/matrix/test_context_commands.py` additions — room-local `!clear` rotation semantics +- [ ] `tests/adapter/matrix/test_files.py` additions — cross-room attachment isolation and shared-root consistency +- [ ] Compose smoke coverage or documented verification command for `docker-compose.prod.yml` and `docker-compose.fullstack.yml` --- @@ -67,8 +65,9 @@ created: 2026-04-27 | Behavior | Requirement | Why Manual | Test Instructions | |----------|-------------|------------|-------------------| -| docker-compose.prod.yml full-stack launch | D-08/D-09 | Requires Docker daemon and lambda-agent:latest image | `docker compose -f docker-compose.prod.yml up` — verify both services start, volume mounts at /agents/ | -| Matrix bot invite + DM flow | D-04/D-05 | Requires live Matrix homeserver | Invite bot to DM, verify welcome message appears | +| Restart after real Matrix room topology exists | PH05-03 | Full recovery depends on live Space hierarchy and persisted homeserver state | Start the bot, provision a Space and chat rooms, stop the bot, remove local SQLite metadata, restart, confirm routing and room labels are rebuilt before live messages are handled | +| Shared `/agents` volume behavior across bot and platform containers | PH05-04 | Container mounts and permissions are environment-dependent | Run `docker compose -f docker-compose.fullstack.yml up`, upload a file in Matrix, confirm the agent sees the relative `workspace_path`, then confirm an agent-created file is readable back from the bot side | +| Operator handoff of prod compose | PH05-05 | Final deploy contract depends on real env files and target host conventions | Run `docker compose -f docker-compose.prod.yml config` on the target deployment checkout and confirm only bot services, required env vars, and shared volumes are present | --- @@ -78,7 +77,7 @@ created: 2026-04-27 - [ ] Sampling continuity: no 3 consecutive tasks without automated verify - [ ] Wave 0 covers all MISSING references - [ ] No watch-mode flags -- [ ] Feedback latency < 30s -- [ ] `nyquist_compliant: true` set in frontmatter +- [x] Feedback latency target tightened to task slices under 60s +- [x] `nyquist_compliant: true` set in frontmatter **Approval:** pending diff --git a/Dockerfile b/Dockerfile index e83ae3b..c04d98a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,8 @@ FROM python:3.11-slim AS base WORKDIR /app +RUN useradd -u 1000 -m appuser +USER appuser ENV PYTHONUNBUFFERED=1 ENV PYTHONPATH=/app @@ -20,25 +22,25 @@ RUN uv sync --no-dev --no-install-project --frozen FROM base AS development +COPY . . +RUN uv sync --no-dev --frozen + # Local fullstack/dev builds can override the SDK with a checked-out agent_api # build context, matching platform-agent's development Dockerfile pattern. COPY --from=agent_api . /agent_api/ RUN python -m pip install --no-cache-dir --ignore-requires-python -e /agent_api/ -COPY . . -RUN uv sync --no-dev --frozen - CMD ["python", "-m", "adapter.matrix.bot"] FROM base AS production +COPY . . +RUN uv sync --no-dev --frozen + # Production builds follow the platform-agent pattern: install the API SDK from # the platform Git repository instead of relying on local external/ clones. ARG LAMBDA_AGENT_API_REF=master RUN python -m pip install --no-cache-dir --ignore-requires-python \ "git+https://git.lambda.coredump.ru/platform/agent_api.git@${LAMBDA_AGENT_API_REF}" -COPY . . -RUN uv sync --no-dev --frozen - CMD ["python", "-m", "adapter.matrix.bot"] diff --git a/README.md b/README.md index 9a1a2fb..3b8a7a6 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,9 @@ Bot container Agent containers /agents/N/ ←── volume ──→ agent_N: /workspace/ ``` -- Бот сохраняет входящий файл в `{workspace_path}/incoming/{stamp}-{file}` и передаёт агенту `attachments=["incoming/{stamp}-{file}"]` -- Агент пишет исходящий файл в свой `/workspace/output/file`, бот читает его из `{workspace_path}/output/file` +- Бот сохраняет входящий файл прямо в `{workspace_path}/{file}` и передаёт агенту `attachments=["{file}"]` +- Если файл с таким именем уже есть, бот сохраняет следующий как `file (1).ext`, `file (2).ext`, как в Windows +- Агент пишет исходящий файл прямо в свой `/workspace/file`, бот читает его из `{workspace_path}/file` - `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml` **3. Конфиг агентов** @@ -128,7 +129,7 @@ agents: - `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент. - `base_url` — HTTP URL агент-эндпоинта (path-based routing через reverse proxy). - `workspace_path` — путь к воркспейсу агента внутри бот-контейнера на shared volume. - Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, агент пишет исходящие в свой `/workspace/`. + Бот сохраняет входящие файлы прямо в `{workspace_path}/`, агент пишет исходящие прямо в свой `/workspace/`. - Для 25-30 агентов продолжайте тот же паттерн: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`. Полный пример с комментариями: `config/matrix-agents.example.yaml` @@ -137,6 +138,15 @@ agents: `docker-compose.prod.yml` — bot-only handoff через published image. Платформа добавляет этот сервис в свой compose рядом с agent containers, монтирует shared volume и задаёт переменные окружения. Этот compose не создаёт и не собирает агент-контейнеры. +Перед redeploy можно проверить реальные agent routes из той же сети, где будет работать бот: +```bash +PYTHONPATH=. uv run python -m tools.check_matrix_agents \ + --config config/matrix-agents.yaml \ + --timeout 5 +``` + +Проверка открывает фактический WebSocket URL каждого агента (`.../v1/agent_ws/{chat_id}/`) и ждёт первый `STATUS`. Для проверки полного запроса к агенту добавьте `--message "ping"`. + Для запуска опубликованного image: ```bash export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest @@ -147,7 +157,7 @@ docker compose --env-file .env -f docker-compose.prod.yml up -d ```text mput1/surfaces-bot:latest -sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be +sha256:2f135f3535f7765d4377b440cdabe41195ad2efbc3e175def159ae4689ef90bd ``` Для сборки и публикации surface image: @@ -183,12 +193,13 @@ rm -f lambda_matrix.db && rm -rf matrix_store ``` Bot (/agents) Agent (/workspace = /agents/N/) - /agents/0/incoming/ ←──── одно и то же хранилище ────→ /workspace/incoming/ - /agents/0/output/ ←────────────────────────────────→ /workspace/output/ + /agents/0/report.pdf ←──── одно и то же хранилище ────→ /workspace/report.pdf + /agents/0/result.txt ←────────────────────────────────→ /workspace/result.txt ``` -- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, например `/agents/17/incoming/report.pdf`, и передаёт агенту `attachments=["incoming/{stamp}-{file}"]` -- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file`, например `/agents/17/output/file`, и отправляет пользователю как Matrix file message +- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/{file}`, например `/agents/17/report.pdf`, и передаёт агенту `attachments=["report.pdf"]` +- **Коллизии имён**: если `/agents/17/report.pdf` уже существует, бот сохранит следующий файл как `/agents/17/report (1).pdf`, затем `/agents/17/report (2).pdf` +- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/file`, бот читает из `{workspace_path}/file`, например `/agents/17/result.txt`, и отправляет пользователю как Matrix file message - `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml` --- diff --git a/adapter/matrix/agent_registry.py b/adapter/matrix/agent_registry.py index f75823c..bf02018 100644 --- a/adapter/matrix/agent_registry.py +++ b/adapter/matrix/agent_registry.py @@ -3,6 +3,7 @@ from __future__ import annotations from collections.abc import Mapping from dataclasses import dataclass, field from pathlib import Path +from typing import Literal import yaml @@ -19,6 +20,16 @@ class AgentDefinition: workspace_path: str = field(default="") +@dataclass(frozen=True) +class AgentAssignment: + agent_id: str | None + source: Literal["configured", "default", "none"] + + @property + def is_default(self) -> bool: + return self.source == "default" + + class AgentRegistry: def __init__( self, @@ -38,6 +49,14 @@ class AgentRegistry: def get_agent_id_for_user(self, matrix_user_id: str) -> str | None: return self._user_agents.get(matrix_user_id) + def resolve_agent_for_user(self, matrix_user_id: str) -> AgentAssignment: + agent_id = self.get_agent_id_for_user(matrix_user_id) + if agent_id is not None: + return AgentAssignment(agent_id=agent_id, source="configured") + if self.agents: + return AgentAssignment(agent_id=self.agents[0].agent_id, source="default") + return AgentAssignment(agent_id=None, source="none") + def _required_text(entry: Mapping[str, object], key: str) -> str: value = entry.get(key) diff --git a/adapter/matrix/bot.py b/adapter/matrix/bot.py index cece1f6..411f037 100644 --- a/adapter/matrix/bot.py +++ b/adapter/matrix/bot.py @@ -1,6 +1,7 @@ from __future__ import annotations import asyncio +import logging import os import re from dataclasses import dataclass @@ -24,21 +25,26 @@ from nio import ( ) from nio.responses import SyncResponse +from adapter.matrix.agent_registry import AgentRegistry, AgentRegistryError, load_agent_registry from adapter.matrix.converter import from_room_event from adapter.matrix.files import ( download_matrix_attachment, matrix_msgtype_for_attachment, resolve_workspace_attachment_path, ) -from adapter.matrix.agent_registry import AgentRegistry, AgentRegistryError, load_agent_registry from adapter.matrix.handlers import register_matrix_handlers -from adapter.matrix.handlers.auth import handle_invite, provision_workspace_chat +from adapter.matrix.handlers.auth import ( + default_agent_notice, + handle_invite, + provision_workspace_chat, + restore_workspace_access, +) from adapter.matrix.handlers.context_commands import ( LOAD_PROMPT, ) -from adapter.matrix.routed_platform import RoutedPlatformClient from adapter.matrix.reconciliation import reconcile_startup_state from adapter.matrix.room_router import resolve_chat_id +from adapter.matrix.routed_platform import RoutedPlatformClient from adapter.matrix.store import ( add_staged_attachment, clear_load_pending, @@ -50,7 +56,6 @@ from adapter.matrix.store import ( remove_staged_attachment_at, set_pending_confirm, set_platform_chat_id, - set_room_agent_id, set_room_meta, ) from core.auth import AuthManager @@ -118,6 +123,26 @@ def _normalize_agent_base_url(url: str) -> str: return urlunsplit((parsed.scheme, parsed.netloc, path, "", "")) +def _ws_debug_enabled() -> bool: + value = os.environ.get("SURFACES_DEBUG_WS", "") + return value.strip().lower() in {"1", "true", "yes", "on"} + + +def _configure_debug_logging() -> None: + if not _ws_debug_enabled(): + return + root_logger = logging.getLogger() + if not root_logger.handlers: + logging.basicConfig( + level=logging.INFO, + format="%(asctime)s [%(levelname)-8s] %(name)s %(message)s", + ) + elif root_logger.level > logging.INFO: + root_logger.setLevel(logging.INFO) + logging.getLogger("lambda_agent_api").setLevel(logging.INFO) + logging.getLogger("lambda_agent_api.agent_api").setLevel(logging.INFO) + + def _agent_base_url_from_env() -> str: if base_url := os.environ.get("AGENT_BASE_URL"): return base_url @@ -135,13 +160,39 @@ def _load_agent_registry_from_env(required: bool = False) -> AgentRegistry | Non ) return None try: - return load_agent_registry(registry_path) + registry = load_agent_registry(registry_path) except (AgentRegistryError, OSError) as exc: raise RuntimeError(f"failed to load matrix agent registry: {registry_path}") from exc + if _ws_debug_enabled(): + logger.warning( + "matrix_agent_registry_loaded", + registry_path=registry_path, + agent_count=len(registry.agents), + ) + for agent in registry.agents: + logger.warning( + "matrix_agent_registry_entry", + registry_path=registry_path, + agent_id=agent.agent_id, + label=agent.label, + configured_base_url=agent.base_url, + normalized_base_url=_normalize_agent_base_url(agent.base_url) + if agent.base_url + else "", + workspace_path=agent.workspace_path, + ) + return registry def _build_platform_from_env(*, store: StateStore, chat_mgr: ChatManager) -> PlatformClient: backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower() + if _ws_debug_enabled(): + logger.warning( + "matrix_platform_backend_selected", + backend=backend, + global_agent_base_url=_agent_base_url_from_env(), + registry_path=os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip(), + ) if backend == "real": prototype_state = PrototypeStateStore() registry = _load_agent_registry_from_env(required=True) @@ -220,6 +271,36 @@ class MatrixBot: await next_platform_chat_id(self.runtime.store), ) + async def _refresh_room_agent_assignment( + self, room_id: str, matrix_user_id: str, room_meta: dict | None + ) -> tuple[dict | None, bool]: + if not room_meta or room_meta.get("redirect_room_id") or self.runtime.registry is None: + return room_meta, False + + assignment = self.runtime.registry.resolve_agent_for_user(matrix_user_id) + updated = dict(room_meta) + should_warn_default = False + + if assignment.source == "configured" and ( + updated.get("agent_id") != assignment.agent_id + or updated.get("agent_assignment") != "configured" + ): + updated["agent_id"] = assignment.agent_id + updated["agent_assignment"] = "configured" + updated.pop("default_agent_notice_sent", None) + elif assignment.source == "default": + if not updated.get("agent_id"): + updated["agent_id"] = assignment.agent_id + if updated.get("agent_id") == assignment.agent_id: + updated["agent_assignment"] = "default" + should_warn_default = not updated.get("default_agent_notice_sent") + updated["default_agent_notice_sent"] = True + + if updated != room_meta: + await set_room_meta(self.runtime.store, room_id, updated) + return updated, should_warn_default + return room_meta, should_warn_default + async def on_room_message(self, room: MatrixRoom, event: RoomMessageText) -> None: if getattr(event, "sender", None) == self.client.user_id: return @@ -228,6 +309,14 @@ class MatrixBot: room_meta = await get_room_meta(self.runtime.store, room.room_id) if room_meta is not None and not room_meta.get("redirect_room_id"): await self._ensure_platform_chat_id(room.room_id, room_meta) + room_meta, warn_default_agent = await self._refresh_room_agent_assignment( + room.room_id, sender, room_meta + ) + if warn_default_agent and not body.startswith("!"): + await self._send_all( + room.room_id, + [OutgoingMessage(chat_id=room.room_id, text=default_agent_notice())], + ) load_pending = await get_load_pending(self.runtime.store, sender, room.room_id) if load_pending is not None and (body.isdigit() or body == "!cancel"): @@ -241,17 +330,97 @@ class MatrixBot: await self._send_all(room.room_id, outgoing) return elif room_meta.get("redirect_room_id"): + display_name = getattr(room, "display_name", None) or sender + if body == "!new": + try: + created = await provision_workspace_chat( + self.client, + sender, + display_name, + self.runtime.platform, + self.runtime.store, + self.runtime.auth_mgr, + self.runtime.chat_mgr, + registry=self.runtime.registry, + ) + except Exception as exc: + logger.warning( + "matrix_entry_room_new_chat_failed", + room_id=room.room_id, + sender=sender, + error=str(exc), + ) + await self._send_all( + room.room_id, + [ + OutgoingMessage( + chat_id=room.room_id, + text="Не удалось создать новый рабочий чат.", + ) + ], + ) + return + + welcome = f"Создал новый рабочий чат {created['room_name']}." + if created.get("agent_assignment") == "default": + welcome = f"{welcome}\n\n{default_agent_notice()}" + await self.client.room_send( + created["chat_room_id"], + "m.room.message", + {"msgtype": "m.text", "body": welcome}, + ) + await set_room_meta( + self.runtime.store, + room.room_id, + { + **room_meta, + "redirect_room_id": created["chat_room_id"], + "redirect_chat_id": created["chat_id"], + }, + ) + await self._send_all( + room.room_id, + [ + OutgoingMessage( + chat_id=room.room_id, + text=( + f"Создал рабочий чат {created['room_name']} " + f"({created['chat_id']}) и отправил приглашение." + ), + ) + ], + ) + return + + restored = await restore_workspace_access( + self.client, + sender, + display_name, + self.runtime.platform, + self.runtime.store, + self.runtime.auth_mgr, + self.runtime.chat_mgr, + registry=self.runtime.registry, + ) redirect_room_id = room_meta["redirect_room_id"] redirect_chat_id = room_meta.get("redirect_chat_id", "рабочий чат") + if restored.get("created_new_chat"): + text = ( + f"Создал новый рабочий чат {restored['room_name']} " + f"({restored['chat_id']}) и отправил приглашение." + ) + else: + text = ( + f"Рабочий чат уже создан: {redirect_chat_id}. " + "Я повторно отправил приглашения в пространство Lambda и рабочие чаты. " + "Чтобы создать новый чат, напишите !new здесь." + ) await self._send_all( room.room_id, [ OutgoingMessage( chat_id=room.room_id, - text=( - f"Рабочий чат уже создан: {redirect_chat_id}. " - "Открой приглашённую комнату для продолжения." - ), + text=text, ) ], ) @@ -302,6 +471,15 @@ class MatrixBot: incoming, ) agent_id = (room_meta or {}).get("agent_id") + if _ws_debug_enabled() and not body.startswith("!"): + logger.warning( + "matrix_incoming_message_route", + room_id=room.room_id, + sender=sender, + local_chat_id=local_chat_id, + agent_id=agent_id, + platform_chat_id=(room_meta or {}).get("platform_chat_id"), + ) workspace_root = self._agent_workspace_root(agent_id) try: outgoing = await self.runtime.dispatcher.dispatch(incoming) @@ -520,6 +698,8 @@ class MatrixBot: f"Привет, {created['user'].display_name or sender}! Пиши — я здесь.\n\n" "Команды: !new · !chats · !rename · !archive · !context · !save · !load · !help" ) + if created.get("agent_assignment") == "default": + welcome = f"{welcome}\n\n{default_agent_notice()}" await set_room_meta( self.runtime.store, room.room_id, @@ -715,6 +895,7 @@ async def send_outgoing( async def main() -> None: + _configure_debug_logging() homeserver = os.environ.get("MATRIX_HOMESERVER") user_id = os.environ.get("MATRIX_USER_ID") device_id = os.environ.get("MATRIX_DEVICE_ID", "") @@ -768,6 +949,15 @@ async def main() -> None: store_path=store_path, request_timeout=client_config.request_timeout, ) + if _ws_debug_enabled(): + logger.warning( + "matrix_ws_debug_enabled", + homeserver=homeserver, + user_id=user_id, + backend=os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower(), + global_agent_base_url=_agent_base_url_from_env(), + registry_path=os.environ.get("MATRIX_AGENT_REGISTRY_PATH", "").strip(), + ) try: await client.sync_forever(timeout=30000, since=since_token) finally: diff --git a/adapter/matrix/files.py b/adapter/matrix/files.py index a6210fb..0845684 100644 --- a/adapter/matrix/files.py +++ b/adapter/matrix/files.py @@ -2,16 +2,16 @@ from __future__ import annotations import mimetypes import re -from datetime import UTC, datetime -from pathlib import Path +from pathlib import Path, PurePosixPath from core.protocol import Attachment -def _sanitize_component(value: str) -> str: - cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", value) - cleaned = cleaned.strip("._-") - return cleaned or "unknown" +def _sanitize_filename(value: str) -> str: + filename = PurePosixPath(str(value).replace("\\", "/")).name.strip() + cleaned = re.sub(r"[\x00-\x1f\x7f<>:\"/\\|?*]+", "_", filename) + cleaned = cleaned.strip(" .") + return cleaned or "attachment.bin" def _default_filename(attachment: Attachment) -> str: @@ -28,38 +28,38 @@ def _default_filename(attachment: Attachment) -> str: return f"{base}{extension}" -def build_workspace_attachment_path( - *, - workspace_root: Path, - matrix_user_id: str, - room_id: str, - filename: str, - timestamp: str | None = None, -) -> tuple[str, Path]: - """Legacy path builder used when no per-agent workspace_path is configured.""" - stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S") - safe_user = _sanitize_component(matrix_user_id.lstrip("@")) - safe_room = _sanitize_component(room_id.lstrip("!")) - safe_name = _sanitize_component(filename) or "attachment.bin" - relative_path = ( - Path("surfaces") / "matrix" / safe_user / safe_room / "inbox" / f"{stamp}-{safe_name}" - ) - return relative_path.as_posix(), workspace_root / relative_path +def _with_copy_index(filename: str, index: int) -> str: + path = Path(filename) + suffix = path.suffix + stem = path.stem if suffix else filename + return f"{stem} ({index}){suffix}" -def build_agent_incoming_path( +def _unique_workspace_relative_path(workspace_root: Path, filename: str) -> tuple[str, Path]: + safe_name = _sanitize_filename(filename) + candidate = workspace_root / safe_name + if not candidate.exists(): + return safe_name, candidate + + index = 1 + while True: + indexed_name = _with_copy_index(safe_name, index) + candidate = workspace_root / indexed_name + if not candidate.exists(): + return indexed_name, candidate + index += 1 + + +def build_agent_workspace_path( *, workspace_root: Path, filename: str, - timestamp: str | None = None, ) -> tuple[str, Path]: - """Per-agent path builder: saves to {workspace_root}/incoming/{stamp}-{filename}. + """Saves user files directly to {workspace_root}/{filename}. + The returned relative path is what gets passed to agent.send_message(attachments=[...]). """ - stamp = timestamp or datetime.now(UTC).strftime("%Y%m%d-%H%M%S") - safe_name = _sanitize_component(filename) or "attachment.bin" - relative_path = Path("incoming") / f"{stamp}-{safe_name}" - return relative_path.as_posix(), workspace_root / relative_path + return _unique_workspace_relative_path(workspace_root, filename) async def download_matrix_attachment( @@ -76,21 +76,11 @@ async def download_matrix_attachment( filename = _default_filename(attachment) - if workspace_root.name and str(workspace_root) not in (".", "/workspace", "/agents"): - # Per-agent workspace configured — use simple incoming/ layout - relative_path, absolute_path = build_agent_incoming_path( - workspace_root=workspace_root, - filename=filename, - timestamp=timestamp, - ) - else: - relative_path, absolute_path = build_workspace_attachment_path( - workspace_root=workspace_root, - matrix_user_id=matrix_user_id, - room_id=room_id, - filename=filename, - timestamp=timestamp, - ) + del matrix_user_id, room_id, timestamp + relative_path, absolute_path = build_agent_workspace_path( + workspace_root=workspace_root, + filename=filename, + ) absolute_path.parent.mkdir(parents=True, exist_ok=True) diff --git a/adapter/matrix/handlers/auth.py b/adapter/matrix/handlers/auth.py index 4616391..064448d 100644 --- a/adapter/matrix/handlers/auth.py +++ b/adapter/matrix/handlers/auth.py @@ -22,6 +22,31 @@ def _default_room_name(chat_id: str) -> str: return f"Чат {suffix}" +def default_agent_notice() -> str: + return ( + "Внимание: ваш Matrix ID не найден в конфиге агентов. " + "Пока используется агент по умолчанию. После добавления вас в конфиг " + "бот переключит существующие комнаты на назначенного агента." + ) + + +async def _invite_if_possible(client: Any, room_id: str, matrix_user_id: str) -> bool: + room_invite = getattr(client, "room_invite", None) + if not callable(room_invite): + return False + try: + await room_invite(room_id, matrix_user_id) + return True + except Exception as exc: + logger.warning( + "matrix_workspace_reinvite_failed", + room_id=room_id, + user=matrix_user_id, + error=str(exc), + ) + return False + + async def provision_workspace_chat( client: Any, matrix_user_id: str, @@ -68,10 +93,11 @@ async def provision_workspace_chat( room_name = room_name_override or _default_room_name(chat_id) agent_id = None + agent_assignment = "none" if registry is not None: - agent_id = registry.get_agent_id_for_user(matrix_user_id) - if agent_id is None and registry.agents: - agent_id = registry.agents[0].agent_id + assignment = registry.resolve_agent_for_user(matrix_user_id) + agent_id = assignment.agent_id + agent_assignment = assignment.source chat_resp = await client.room_create( name=room_name, @@ -110,6 +136,7 @@ async def provision_workspace_chat( "space_id": space_id, "platform_chat_id": platform_chat_id, "agent_id": agent_id, + "agent_assignment": agent_assignment, }, ) await chat_mgr.get_or_create( @@ -126,6 +153,64 @@ async def provision_workspace_chat( "chat_room_id": chat_room_id, "chat_id": chat_id, "room_name": room_name, + "agent_assignment": agent_assignment, + "agent_id": agent_id, + } + + +async def restore_workspace_access( + client: Any, + matrix_user_id: str, + display_name: str, + platform, + store, + auth_mgr, + chat_mgr, + registry: AgentRegistry | None = None, +) -> dict: + user_meta = await get_user_meta(store, matrix_user_id) or {} + space_id = user_meta.get("space_id") + if not space_id: + created = await provision_workspace_chat( + client, + matrix_user_id, + display_name, + platform, + store, + auth_mgr, + chat_mgr, + room_name_override="Чат 1", + registry=registry, + ) + return {**created, "reinvited_rooms": [], "created_new_chat": True} + + await auth_mgr.confirm(matrix_user_id) + await _invite_if_possible(client, space_id, matrix_user_id) + + chats = await chat_mgr.list_active(matrix_user_id) + if not chats: + created = await provision_workspace_chat( + client, + matrix_user_id, + display_name, + platform, + store, + auth_mgr, + chat_mgr, + registry=registry, + ) + return {**created, "reinvited_rooms": [], "created_new_chat": True} + + reinvited_rooms = [] + for chat in chats: + if chat.surface_ref: + if await _invite_if_possible(client, chat.surface_ref, matrix_user_id): + reinvited_rooms.append(chat.surface_ref) + + return { + "space_id": space_id, + "reinvited_rooms": reinvited_rooms, + "created_new_chat": False, } @@ -146,6 +231,29 @@ async def handle_invite( existing = await get_user_meta(store, matrix_user_id) if existing and existing.get("space_id"): + restored = await restore_workspace_access( + client, + matrix_user_id, + display_name, + platform, + store, + auth_mgr, + chat_mgr, + registry=registry, + ) + body = "Я отправил повторные приглашения в пространство Lambda и рабочие чаты." + if restored.get("created_new_chat"): + body = ( + f"Создал новый рабочий чат {restored['room_name']} " + f"({restored['chat_id']}) и отправил приглашение." + ) + if restored.get("agent_assignment") == "default": + body = f"{body}\n\n{default_agent_notice()}" + await client.room_send( + room.room_id, + "m.room.message", + {"msgtype": "m.text", "body": body}, + ) return try: @@ -168,6 +276,8 @@ async def handle_invite( f"Привет, {created['user'].display_name or matrix_user_id}! Пиши — я здесь.\n\n" "Команды: !new · !chats · !rename · !archive · !clear · !help" ) + if created.get("agent_assignment") == "default": + welcome = f"{welcome}\n\n{default_agent_notice()}" await client.room_send( created["chat_room_id"], "m.room.message", diff --git a/adapter/matrix/handlers/chat.py b/adapter/matrix/handlers/chat.py index 6508ee6..645e9cd 100644 --- a/adapter/matrix/handlers/chat.py +++ b/adapter/matrix/handlers/chat.py @@ -8,6 +8,7 @@ from nio.api import RoomVisibility from nio.responses import RoomCreateError from adapter.matrix.agent_registry import AgentRegistry +from adapter.matrix.handlers.auth import default_agent_notice from adapter.matrix.store import ( get_user_meta, next_chat_id, @@ -107,10 +108,11 @@ def make_handle_new_chat( ) agent_id = None + agent_assignment = "none" if registry is not None: - agent_id = registry.get_agent_id_for_user(event.user_id) - if agent_id is None and registry.agents: - agent_id = registry.agents[0].agent_id + assignment = registry.resolve_agent_for_user(event.user_id) + agent_id = assignment.agent_id + agent_assignment = assignment.source room_meta: dict = { "room_type": "chat", @@ -120,6 +122,7 @@ def make_handle_new_chat( "space_id": space_id, "platform_chat_id": platform_chat_id, "agent_id": agent_id, + "agent_assignment": agent_assignment, } await set_room_meta(store, room_id, room_meta) ctx = await chat_mgr.get_or_create( @@ -129,10 +132,13 @@ def make_handle_new_chat( surface_ref=room_id, name=room_name, ) + text = f"Создан чат: {ctx.display_name} ({ctx.chat_id})" + if agent_assignment == "default": + text = f"{text}\n\n{default_agent_notice()}" return [ OutgoingMessage( chat_id=event.chat_id, - text=f"Создан чат: {ctx.display_name} ({ctx.chat_id})", + text=text, ) ] diff --git a/adapter/matrix/reconciliation.py b/adapter/matrix/reconciliation.py index d723058..835bd5d 100644 --- a/adapter/matrix/reconciliation.py +++ b/adapter/matrix/reconciliation.py @@ -48,7 +48,9 @@ def _chat_id_from_room(room: object, existing_meta: dict | None) -> str | None: return None -def _space_id_for_room(room: object, rooms_by_id: dict[str, object], existing_meta: dict | None) -> str | None: +def _space_id_for_room( + room: object, rooms_by_id: dict[str, object], existing_meta: dict | None +) -> str | None: existing_space_id = (existing_meta or {}).get("space_id") if isinstance(existing_space_id, str) and existing_space_id: return existing_space_id @@ -69,7 +71,9 @@ def _space_id_for_room(room: object, rooms_by_id: dict[str, object], existing_me return None -def _matrix_user_id_for_room(room: object, bot_user_id: str | None, existing_meta: dict | None) -> str | None: +def _matrix_user_id_for_room( + room: object, bot_user_id: str | None, existing_meta: dict | None +) -> str | None: existing_user_id = (existing_meta or {}).get("matrix_user_id") if isinstance(existing_user_id, str) and existing_user_id: return existing_user_id @@ -128,11 +132,26 @@ async def reconcile_startup_state(client: object, runtime: object) -> Reconcilia if not room_meta.get("agent_id"): registry = getattr(runtime, "registry", None) if registry is not None: - agent_id = registry.get_agent_id_for_user(matrix_user_id) - if agent_id is None and registry.agents: - agent_id = registry.agents[0].agent_id - if agent_id: - room_meta["agent_id"] = agent_id + assignment = registry.resolve_agent_for_user(matrix_user_id) + if assignment.agent_id: + room_meta["agent_id"] = assignment.agent_id + room_meta["agent_assignment"] = assignment.source + else: + registry = getattr(runtime, "registry", None) + if registry is not None: + assignment = registry.resolve_agent_for_user(matrix_user_id) + if assignment.source == "configured" and ( + room_meta.get("agent_id") != assignment.agent_id + or room_meta.get("agent_assignment") != "configured" + ): + room_meta["agent_id"] = assignment.agent_id + room_meta["agent_assignment"] = "configured" + elif ( + assignment.source == "default" + and room_meta.get("agent_id") == assignment.agent_id + and not room_meta.get("agent_assignment") + ): + room_meta["agent_assignment"] = "default" if existing_meta is None: result.recovered_rooms += 1 @@ -153,7 +172,9 @@ async def reconcile_startup_state(client: object, runtime: object) -> Reconcilia user_meta = dict(await get_user_meta(runtime.store, matrix_user_id) or {}) user_meta["space_id"] = user_meta.get("space_id") or recovered_space_id next_chat_index = max_chat_index_by_user[matrix_user_id] + 1 - user_meta["next_chat_index"] = max(int(user_meta.get("next_chat_index", 1)), next_chat_index) + user_meta["next_chat_index"] = max( + int(user_meta.get("next_chat_index", 1)), next_chat_index + ) await set_user_meta(runtime.store, matrix_user_id, user_meta) return result diff --git a/adapter/matrix/routed_platform.py b/adapter/matrix/routed_platform.py index 8f505e5..3f9adc8 100644 --- a/adapter/matrix/routed_platform.py +++ b/adapter/matrix/routed_platform.py @@ -1,7 +1,10 @@ from __future__ import annotations +import os from collections.abc import AsyncIterator, Mapping +import structlog + from adapter.matrix.store import get_room_meta from core.chat import ChatManager from core.store import StateStore @@ -15,6 +18,13 @@ from sdk.interface import ( UserSettings, ) +logger = structlog.get_logger(__name__) + + +def _ws_debug_enabled() -> bool: + value = os.environ.get("SURFACES_DEBUG_WS", "") + return value.strip().lower() in {"1", "true", "yes", "on"} + class RoutedPlatformClient(PlatformClient): def __init__( @@ -77,7 +87,9 @@ class RoutedPlatformClient(PlatformClient): if callable(close): await close() - async def _resolve_delegate(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]: + async def _resolve_delegate( + self, user_id: str, local_chat_id: str + ) -> tuple[PlatformClient, str]: chat = await self._chat_mgr.get(local_chat_id, user_id) if chat is None: raise PlatformError( @@ -107,4 +119,15 @@ class RoutedPlatformClient(PlatformClient): code="MATRIX_AGENT_NOT_FOUND", ) + if _ws_debug_enabled(): + logger.warning( + "matrix_route_resolved", + user_id=user_id, + local_chat_id=local_chat_id, + surface_ref=chat.surface_ref, + agent_id=str(agent_id), + platform_chat_id=str(platform_chat_id), + delegate_type=type(delegate).__name__, + ) + return delegate, str(platform_chat_id) diff --git a/config/matrix-agents.example.yaml b/config/matrix-agents.example.yaml index 30d41a2..84221eb 100644 --- a/config/matrix-agents.example.yaml +++ b/config/matrix-agents.example.yaml @@ -12,7 +12,7 @@ # base_url — HTTP/WS URL of this agent's endpoint # (overrides the global AGENT_BASE_URL env var for this agent) # workspace_path — absolute path to this agent's workspace directory inside the bot container -# (the bot saves incoming files here and reads outgoing files from here) +# (the bot saves incoming files directly here and reads outgoing files from here) # Example: /agents/0 means the bot mounts the shared volume at /agents/ # and this agent's files live under /agents/0/ diff --git a/config/matrix-agents.smoke.yaml b/config/matrix-agents.smoke.yaml new file mode 100644 index 0000000..9b357fe --- /dev/null +++ b/config/matrix-agents.smoke.yaml @@ -0,0 +1,10 @@ +agents: + - id: agent-0 + label: "Smoke Agent 0" + base_url: "http://agent-proxy:7000/agent_0/" + workspace_path: "/agents/0" + + - id: agent-1 + label: "Smoke Agent 1" + base_url: "http://agent-proxy:7000/agent_1/" + workspace_path: "/agents/1" diff --git a/docker-compose.smoke.timeout.yml b/docker-compose.smoke.timeout.yml new file mode 100644 index 0000000..c8f4ba3 --- /dev/null +++ b/docker-compose.smoke.timeout.yml @@ -0,0 +1,18 @@ +services: + agent-proxy: + volumes: + - ./docker/nginx/smoke-agents-timeout.conf:/etc/nginx/nginx.conf:ro + depends_on: + agent-no-status: + condition: service_started + + agent-no-status: + build: + context: . + dockerfile: Dockerfile + target: production + args: + LAMBDA_AGENT_API_REF: ${LAMBDA_AGENT_API_REF:-master} + environment: + PYTHONUNBUFFERED: "1" + command: ["python", "-m", "tools.no_status_agent", "--host", "0.0.0.0", "--port", "8000"] diff --git a/docker-compose.smoke.yml b/docker-compose.smoke.yml new file mode 100644 index 0000000..ed4e8b8 --- /dev/null +++ b/docker-compose.smoke.yml @@ -0,0 +1,109 @@ +services: + surface-smoke: + build: + context: . + dockerfile: Dockerfile + target: production + args: + LAMBDA_AGENT_API_REF: ${LAMBDA_AGENT_API_REF:-master} + environment: + PYTHONUNBUFFERED: "1" + SMOKE_TIMEOUT: ${SMOKE_TIMEOUT:-5} + volumes: + - agents:/agents + - ./config:/app/config:ro + depends_on: + agent-proxy: + condition: service_healthy + command: > + sh -lc " + python -m tools.check_matrix_agents --config /app/config/matrix-agents.smoke.yaml --timeout ${SMOKE_TIMEOUT:-5} + " + + agent-proxy: + image: nginx:1.27-alpine + volumes: + - ./docker/nginx/smoke-agents.conf:/etc/nginx/nginx.conf:ro + healthcheck: + test: + - CMD-SHELL + - nc -z 127.0.0.1 7000 + interval: 2s + timeout: 2s + retries: 15 + start_period: 2s + depends_on: + agent-0: + condition: service_healthy + agent-1: + condition: service_healthy + ports: + - "${SMOKE_PROXY_PORT:-7000}:7000" + + agent-0: + build: + context: ./external/platform-agent + target: development + additional_contexts: + agent_api: ./external/platform-agent_api + environment: + PYTHONUNBUFFERED: "1" + AGENT_ID: ${AGENT_0_ID:-agent-0} + PROVIDER_MODEL: ${PROVIDER_MODEL:-debug-model} + PROVIDER_URL: ${PROVIDER_URL:-http://provider.invalid/v1} + PROVIDER_API_KEY: ${PROVIDER_API_KEY:-debug-key} + volumes: + - ./external/platform-agent/src:/app/src + - ./external/platform-agent_api:/agent_api + - agents:/shared-agents + healthcheck: + test: + - CMD-SHELL + - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()" + interval: 5s + timeout: 3s + retries: 12 + start_period: 5s + command: > + sh -lc " + mkdir -p /shared-agents/0 && + rm -rf /workspace && + ln -s /shared-agents/0 /workspace && + exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --no-access-log + " + + agent-1: + build: + context: ./external/platform-agent + target: development + additional_contexts: + agent_api: ./external/platform-agent_api + environment: + PYTHONUNBUFFERED: "1" + AGENT_ID: ${AGENT_1_ID:-agent-1} + PROVIDER_MODEL: ${PROVIDER_MODEL:-debug-model} + PROVIDER_URL: ${PROVIDER_URL:-http://provider.invalid/v1} + PROVIDER_API_KEY: ${PROVIDER_API_KEY:-debug-key} + volumes: + - ./external/platform-agent/src:/app/src + - ./external/platform-agent_api:/agent_api + - agents:/shared-agents + healthcheck: + test: + - CMD-SHELL + - python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/openapi.json', timeout=2).read()" + interval: 5s + timeout: 3s + retries: 12 + start_period: 5s + command: > + sh -lc " + mkdir -p /shared-agents/1 && + rm -rf /workspace && + ln -s /shared-agents/1 /workspace && + exec /app/.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000 --no-access-log + " + +volumes: + agents: + name: ${SURFACES_SMOKE_VOLUME:-surfaces-smoke-agents} diff --git a/docker/nginx/smoke-agents-timeout.conf b/docker/nginx/smoke-agents-timeout.conf new file mode 100644 index 0000000..03c7e79 --- /dev/null +++ b/docker/nginx/smoke-agents-timeout.conf @@ -0,0 +1,28 @@ +events {} + +http { + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + + server { + listen 7000; + + location /agent_0/ { + proxy_pass http://agent-0:8000/; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + + location /agent_1/ { + proxy_pass http://agent-no-status:8000/; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + } +} diff --git a/docker/nginx/smoke-agents.conf b/docker/nginx/smoke-agents.conf new file mode 100644 index 0000000..e3bcaab --- /dev/null +++ b/docker/nginx/smoke-agents.conf @@ -0,0 +1,28 @@ +events {} + +http { + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + + server { + listen 7000; + + location /agent_0/ { + proxy_pass http://agent-0:8000/; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + + location /agent_1/ { + proxy_pass http://agent-1:8000/; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + } + } +} diff --git a/docs/deploy-architecture.md b/docs/deploy-architecture.md index 0d9a872..e838611 100644 --- a/docs/deploy-architecture.md +++ b/docs/deploy-architecture.md @@ -68,7 +68,7 @@ agents: - `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка. - `agents[].base_url` — HTTP URL агент-эндпоинта. Бот подключается через AgentApi. - `agents[].workspace_path` — абсолютный путь к воркспейсу агента **внутри контейнера бота** (т.е. на shared volume). - Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, читает исходящие из `{workspace_path}/`. + Бот сохраняет входящие файлы прямо в `{workspace_path}/`, читает исходящие из `{workspace_path}/`. - Для 25-30 агентов продолжайте тот же паттерн до нужного номера: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`. ## Surface Image Build Contract @@ -89,7 +89,7 @@ Published image: ```text mput1/surfaces-bot:latest -sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be +sha256:2f135f3535f7765d4377b440cdabe41195ad2efbc3e175def159ae4689ef90bd ``` `SURFACES_BOT_IMAGE` должен указывать на registry namespace, куда текущий Docker account может пушить. Ошибка `insufficient_scope` означает, что пользователь не залогинен в этот namespace, repository не создан, или у аккаунта нет push-доступа. @@ -153,14 +153,15 @@ AgentApi( ### Пользователь → Агент (входящий файл) 1. Matrix-бот получает файл от пользователя -2. Сохраняет в workspace агента: `/agents/{N}/incoming/{filename}` -3. Вызывает `agent.send_message(text, attachments=["incoming/filename"])` +2. Сохраняет в workspace агента: `/agents/{N}/{filename}` +3. Если файл уже существует, выбирает следующее имя: `filename (1).ext`, `filename (2).ext` +4. Вызывает `agent.send_message(text, attachments=["filename"])` — путь относительно `/workspace` агента ### Агент → Пользователь (исходящий файл) -1. Агент эмитит `MsgEventSendFile(path="output/report.pdf")` -2. Matrix-бот читает файл: `/agents/{N}/output/report.pdf` +1. Агент эмитит `MsgEventSendFile(path="report.pdf")` +2. Matrix-бот читает файл: `/agents/{N}/report.pdf` 3. Отправляет как Matrix file message пользователю **Ключевое:** production handoff через `docker-compose.prod.yml` и internal E2E через `docker-compose.fullstack.yml` используют один и тот же `/agents` contract на стороне поверхности. Прямой HTTP-доступ к файлам не нужен. diff --git a/docs/max-surface-guide.md b/docs/max-surface-guide.md new file mode 100644 index 0000000..15b98f1 --- /dev/null +++ b/docs/max-surface-guide.md @@ -0,0 +1,340 @@ +# Руководство по созданию новой поверхности Max + +Этот документ описывает, как написать новую поверхность для Max по образцу текущей Matrix-поверхности в ветке `feat/deploy`. + +Он основан на актуальной реализации Matrix surface в репозитории и отражает текущую продакшн-логику, а не устаревший легаси. + +--- + +## 1. Общая архитектура + +### 1.1. Что такое поверхность + +Поверхность — это тонкий адаптер между конкретной платформой (Max) и общим ядром бота. + +В репозитории есть разделение: + +- `core/` — общее ядро и бизнес-логика +- `adapter//` — реализация конкретной поверхности +- `sdk/real.py` — работа с реальной платформой / агентом +- `config/` — статическая конфигурация агентов +- `docs/surface-protocol.md` — общий контракт поверхностей + +### 1.2. Как это работает + +Поверхность должна: + +- принимать нативные события от Max +- преобразовывать их в единый внутренний контракт (`IncomingMessage`, `IncomingCommand`, `IncomingCallback`) +- передавать их в `core` +- получать ответы из `core` (`OutgoingMessage`, `OutgoingUI`, `OutgoingTyping`, `OutgoingNotification`) +- преобразовывать ответы обратно в нативные Max-сообщения + +Поверхность не должна: + +- управлять жизненным циклом агентских контейнеров +- хранить долгую историю бесед вне `core`/платформы +- аутентифицировать пользователей сама (если это не часть Max API) + +--- + +## 2. Структура новой поверхности + +### 2.1. Основные каталоги + +Рекомендуемая структура для Max: + +``` +adapter/max/ + bot.py + converter.py + agent_registry.py + files.py + handlers/ + store.py +``` + +### 2.2. Принцип reuse + +По примеру Matrix surface, Max surface должен переиспользовать общий `core` и общий `sdk`. + +Не дублируйте бизнес-логику, а реализуйте только адаптер: + +- `adapter/max/converter.py` — конвертация событий Max ⇄ внутренние структуры +- `adapter/max/bot.py` — основной runtime, старт Max client, loop, отправка/прием +- `adapter/max/agent_registry.py` — загрузка `config/max-agents.yaml` +- `adapter/max/files.py` — хранение входящих/исходящих вложений + +--- + +## 3. Контракт входящих/исходящих событий + +### 3.1. Внутренний формат + +Смотрите `core/protocol.py`. Основные типы: + +- `IncomingMessage` — обычное текстовое сообщение + вложения +- `IncomingCommand` — управляющая команда +- `IncomingCallback` — подтверждение / интерактивные действия +- `OutgoingMessage` — ответ пользователю +- `OutgoingUI` — интерфейсные элементы (кнопки и т.п.) +- `OutgoingTyping` — индикатор печати +- `OutgoingNotification` — системное уведомление + +### 3.2. Пример конверсии Matrix + +В Matrix-реализации `adapter/matrix/converter.py`: + +- текст `!yes` / `!no` превращается в `IncomingCallback` с `action: confirm/cancel` +- `!list`/`!remove` говорят не агенту, а surface-процессу +- вложения `m.file`, `m.image`, `m.audio`, `m.video` нормализуются в `Attachment` + +Для Max реализуйте аналогичную логику для native команд вашего клиента. + +--- + +## 4. Реестр агентов и маршрутизация + +### 4.1. Что хранит реестр + +В текущей Matrix реализации есть `config/matrix-agents.yaml` и `adapter/matrix/agent_registry.py`. + +Структура: + +```yaml +user_agents: + "@user0:matrix.example.org": agent-0 + "@user1:matrix.example.org": agent-1 + +agents: + - id: agent-0 + label: "Agent 0" + base_url: "http://lambda.coredump.ru:7000/agent_0/" + workspace_path: "/agents/0" +``` + +### 4.2. Логика выбора агента + +- `user_agents` маппит конкретного пользователя на `agent_id` +- если user_id не найден, используется первый агент из списка +- `agents[].base_url` определяет URL агента +- `agents[].workspace_path` определяет путь внутри surface-контейнера для этого агента + +Это важно: именно на этом контракте строится разделение агентов по рабочим каталогам. + +### 4.3. Рекомендуемая Max-версия + +Создайте `config/max-agents.yaml` с тем же смыслом. + +- `user_agents` — маппинг Max user_id → agent_id +- `agents` — список агентов +- `workspace_path` для каждого агента должен быть абсолютным путем внутри surface-контейнера, например `/agents/0` + +--- + +## 5. Файловый контракт + +### 5.1. Shared volume + +Текущее Matrix-решение использует shared volume: + +- surface монтирует общий том как `/agents` +- каждый агент видит свою поддиректорию как `/workspace` + +Топология: + +``` +Bot (/agents) Agent (/workspace = /agents/N/) + /agents/0/report.pdf ←──→ /workspace/report.pdf +``` + +### 5.2. Правила записи файлов + +В `adapter/matrix/files.py` реализовано: + +- входящий файл сохраняется прямо в `{workspace_root}/{filename}` +- возвращается путь `workspace_path` относительный внутри рабочего каталога агента +- при коллизии имен создаётся `file (1).ext`, `file (2).ext` +- `Attachment.workspace_path` передаётся агенту + +Для исходящих файлов: + +- surface читает файл из `workspace_root / workspace_path` +- загружает его в платформу + +### 5.3. Пример поведения + +- Пользователь отправляет файл → surface скачивает файл и кладёт его в agent workspace +- Агент получает `attachments=["report.pdf"]` и работает с относительным `workspace_path` +- Агент пишет результат в `/workspace/result.txt` +- surface читает `/agents/{N}/result.txt` и отправляет файл пользователю + +--- + +## 6. Чат-менеджмент и контекст + +### 6.1. `platform_chat_id` + +Matrix-реализация использует `platform_chat_id` как стабильный идентификатор чата на стороне агента. + +- `room_meta.platform_chat_id` определяется и сохраняется в `adapter/matrix/store.py` +- `reconcile_startup_state()` восстанавливает отсутствующие `platform_chat_id` при рестарте +- `RoutedPlatformClient` перенаправляет запросы агенту по `agent_id` + `platform_chat_id` + +Для Max surface тот же принцип: + +- каждая внешняя беседа должна привязываться к одному внутреннему `chat_id` +- этот `chat_id` используется для вызовов агента +- если в Max есть несколько комнат/топиков, каждая должна иметь свой `surface_ref` + +### 6.2. Команды управления чатами + +Matrix поддерживает следующие команды, которые нужно сохранить в Max: + +- `!new [название]` — создать новый чат +- `!chats` — список активных чатов +- `!rename <название>` — переименовать текущий чат +- `!archive` — архивировать чат +- `!clear` / `!reset` — сбросить контекст текущего чата +- `!yes` / `!no` — подтвердить или отменить действие агента +- `!list` — показать очередь вложений +- `!remove ` / `!remove all` — удалить вложение из очереди +- `!help` — справка + +Эти команды реализованы в Matrix через `adapter/matrix/handlers/`. + +### 6.3. Очередь вложений + +Matrix surface поддерживает staged attachments: + +- файл может быть отправлен без текста +- surface сохраняет файл в `staged_attachments` для конкретного room_id + user_id +- следующий текст отправляется агенту вместе со всеми файлами из очереди + +В Max можно реализовать ту же модель: + +- `!list` показывает текущую очередь +- `!remove` удаляет файл из очереди +- команда-индикатор или следующее текстовое сообщение отправляет queued attachments агенту + +--- + +## 7. Runtime и окружение + +### 7.1. Переменные среды + +Для Matrix surface текущий runtime ожидает: + +- `MATRIX_HOMESERVER` — URL Matrix-сервера +- `MATRIX_USER_ID` — `@bot:example.org` +- `MATRIX_PASSWORD` или `MATRIX_ACCESS_TOKEN` +- `MATRIX_PLATFORM_BACKEND` — должно быть `real` для продакшна +- `MATRIX_AGENT_REGISTRY_PATH` — путь к `config/matrix-agents.yaml` +- `AGENT_BASE_URL` — fallback URL агента +- `SURFACES_WORKSPACE_DIR` — путь к shared volume внутри контейнера (по умолчанию `/workspace` в коде, но в docs рекомендуют `/agents`) + +Для Max surface используйте аналогичные переменные: + +- `MAX_PLATFORM_BACKEND=real` +- `MAX_AGENT_REGISTRY_PATH=/app/config/max-agents.yaml` +- `SURFACES_WORKSPACE_DIR=/agents` +- `AGENT_BASE_URL` — если хотите общий fallback + +### 7.2. Environment contract + +В коде `adapter/matrix/bot.py`: + +- `_agent_base_url_from_env()` читает `AGENT_BASE_URL` или `AGENT_WS_URL` +- `_load_agent_registry_from_env()` читает `MATRIX_AGENT_REGISTRY_PATH` +- `_build_platform_from_env()` выбирает `RealPlatformClient` при `MATRIX_PLATFORM_BACKEND=real` + +В Max surface реализуйте ту же логику, заменив префиксы на `MAX_`. + +--- + +## 8. Тестирование и валидация + +### 8.1. Юнит-тесты + +В ветке есть покрытие для Matrix surface: + +- `tests/adapter/matrix/test_files.py` +- `tests/adapter/matrix/test_dispatcher.py` +- `tests/adapter/matrix/test_routed_platform.py` +- `tests/adapter/matrix/test_reconciliation.py` +- `tests/adapter/matrix/test_context_commands.py` + +Для Max создайте аналогичные тесты: + +- проверка загрузки вложений +- проверка маршрутизации по `agent_id` +- проверка восстановления `platform_chat_id` +- проверка конвертации команд + +### 8.2. Smoke-проверка deployment + +Для Matrix surface есть `docker-compose.prod.yml` и `docker-compose.fullstack.yml`. + +Для Max surface должно быть достаточно: + +- bot-only production deployment +- shared volume `/agents` +- независимая проверка `config/max-agents.yaml` +- проверка, что surface запускается без локального агента + +### 8.3. Проверка контрактов + +Особое внимание: + +- `agent_registry` должен загружать `workspace_path` +- file flow должен поддерживать `workspace_path` в `Attachment` +- отправка файлов должна использовать `resolve_workspace_attachment_path()` +- `platform_chat_id` должен существовать до вызова агента + +--- + +## 9. Реализация шаг за шагом + +1. Скопировать `adapter/matrix/` как шаблон для `adapter/max/`. +2. Сделать `adapter/max/converter.py`: + - превратить native Max-сообщения в `IncomingMessage` + - превратить команды в `IncomingCommand` + - превратить yes/no-подтверждения в `IncomingCallback` +3. Сделать `adapter/max/agent_registry.py` на основе `adapter/matrix/agent_registry.py`. +4. Сделать `adapter/max/files.py` на основе `adapter/matrix/files.py`. +5. Сделать `adapter/max/bot.py`: + - инстанцировать runtime + - читать env vars `MAX_*` + - загружать реестр агентов + - обрабатывать входящие события + - отправлять `Outgoing*` обратно в Max +6. Реализовать команды управления чатами и очередь вложений. +7. Прописать `config/max-agents.yaml`. +8. Прописать `docker-compose.max.yml` или аналог, чтобы surface монтировал `/agents`. +9. Написать тесты по аналогии с `tests/adapter/matrix/`. +10. Проверить, что все env vars читаются из окружения и не зависят от устаревших Matrix-переменных. + +--- + +## 10. Важные замечания + +- Текущий Matrix surface на ветке `feat/deploy` — активная реализация, а не устаревший легаси. +- Документация и код согласованы: `agent_registry`, `files`, `routed_platform`, `reconciliation` работают вместе. +- Обязательно явно задавайте `SURFACES_WORKSPACE_DIR=/agents` в production, если `workspace_path` в реестре указывает на `/agents/*`. +- Для Max surface сохраните ту же архитектуру: surface = thin adapter, агенты = внешние сервисы. +- Не пытайтесь в surface реализовывать логику запуска/стопа агент-контейнеров. + +--- + +## 11. Полезные ссылки внутри репозитория + +- `README.md` +- `docs/deploy-architecture.md` +- `docs/surface-protocol.md` +- `adapter/matrix/bot.py` +- `adapter/matrix/converter.py` +- `adapter/matrix/agent_registry.py` +- `adapter/matrix/files.py` +- `adapter/matrix/routed_platform.py` +- `adapter/matrix/reconciliation.py` +- `tests/adapter/matrix/` diff --git a/docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md b/docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md new file mode 100644 index 0000000..a5227e8 --- /dev/null +++ b/docs/superpowers/plans/2026-04-24-matrix-multi-agent-routing-and-restart-state.md @@ -0,0 +1,855 @@ +# Matrix Multi-Agent Routing And Restart State Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add Matrix multi-agent routing with user agent selection, room-level agent binding, and durable surface state that survives normal restart. + +**Architecture:** Keep the shared `PlatformClient` protocol unchanged. Add a Matrix-specific routing facade that translates local Matrix chat identity into `(agent_id, platform_chat_id)` and delegates to one `RealPlatformClient` per configured agent. Persist only durable routing state in the existing SQLite-backed surface store and deliberately drop temporary UX state on restart. + +**Tech Stack:** Python 3.11, matrix-nio, structlog, PyYAML, pytest, pytest-asyncio + +--- + +## File Structure + +- Create: `adapter/matrix/agent_registry.py` + Purpose: load and validate the YAML agent registry used by Matrix runtime. +- Create: `adapter/matrix/routed_platform.py` + Purpose: implement a Matrix-specific `PlatformClient` facade that resolves room bindings and delegates to per-agent `RealPlatformClient` instances. +- Create: `adapter/matrix/handlers/agent.py` + Purpose: implement `!agent` listing and selection behavior. +- Create: `tests/adapter/matrix/test_agent_registry.py` + Purpose: cover YAML loading and registry validation. +- Create: `tests/adapter/matrix/test_routed_platform.py` + Purpose: cover room-target resolution and per-agent delegation without changing the shared protocol. +- Create: `tests/adapter/matrix/test_agent_handler.py` + Purpose: cover `!agent` UX and persistence of `selected_agent_id`. +- Create: `tests/adapter/matrix/test_restart_persistence.py` + Purpose: prove durable user/room state and `PLATFORM_CHAT_SEQ_KEY` survive runtime recreation with SQLite. +- Create: `config/matrix-agents.example.yaml` + Purpose: document the expected agent registry format. +- Modify: `pyproject.toml` + Purpose: add YAML parsing dependency required by the runtime registry loader. +- Modify: `.env.example` + Purpose: document the config path env var for the Matrix agent registry. +- Modify: `README.md` + Purpose: document the new config file, `!agent`, and restart persistence expectations. +- Modify: `adapter/matrix/store.py` + Purpose: add helpers for `selected_agent_id`, room `agent_id`, and explicit sequence persistence semantics. +- Modify: `adapter/matrix/bot.py` + Purpose: load the agent registry, construct the routed platform facade, keep local Matrix chat ids through dispatch, and enforce stale/unbound room behavior before dispatch. +- Modify: `adapter/matrix/handlers/__init__.py` + Purpose: register the new `!agent` command. +- Modify: `adapter/matrix/handlers/chat.py` + Purpose: require a selected agent for `!new` and bind new rooms to that agent. +- Modify: `adapter/matrix/handlers/context_commands.py` + Purpose: keep context commands compatible with local chat ids and routed platform delegation. +- Modify: `adapter/matrix/handlers/settings.py` + Purpose: expose `!agent` in help text. +- Modify: `tests/adapter/matrix/test_dispatcher.py` + Purpose: cover pre-dispatch gating, stale room behavior, and `!new` semantics. +- Modify: `tests/adapter/matrix/test_context_commands.py` + Purpose: keep load/reset/context flows aligned with the routed platform facade. + +--- + +### Task 1: Add The Agent Registry And Configuration Wiring + +**Files:** +- Create: `adapter/matrix/agent_registry.py` +- Create: `tests/adapter/matrix/test_agent_registry.py` +- Create: `config/matrix-agents.example.yaml` +- Modify: `pyproject.toml` +- Modify: `.env.example` +- Modify: `README.md` + +- [ ] **Step 1: Write the failing registry tests** + +```python +# tests/adapter/matrix/test_agent_registry.py +from pathlib import Path + +import pytest + +from adapter.matrix.agent_registry import AgentRegistryError, load_agent_registry + + +def test_load_agent_registry_reads_yaml_entries(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-2\n" + " label: Research\n", + encoding="utf-8", + ) + + registry = load_agent_registry(path) + + assert [agent.agent_id for agent in registry.agents] == ["agent-1", "agent-2"] + assert registry.get("agent-1").label == "Analyst" + + +def test_load_agent_registry_rejects_duplicate_ids(tmp_path: Path): + path = tmp_path / "agents.yaml" + path.write_text( + "agents:\n" + " - id: agent-1\n" + " label: Analyst\n" + " - id: agent-1\n" + " label: Duplicate\n", + encoding="utf-8", + ) + + with pytest.raises(AgentRegistryError, match="duplicate agent id"): + load_agent_registry(path) +``` + +- [ ] **Step 2: Run the registry tests to verify they fail** + +Run: `uv run pytest tests/adapter/matrix/test_agent_registry.py -q` + +Expected: FAIL with `ModuleNotFoundError` or `ImportError` for `adapter.matrix.agent_registry`. + +- [ ] **Step 3: Add the YAML dependency and implement the registry loader** + +```toml +# pyproject.toml +dependencies = [ + "aiogram>=3.4,<4", + "matrix-nio>=0.21", + "pydantic>=2.5", + "structlog>=24.1", + "python-dotenv>=1.0", + "httpx>=0.27", + "aiohttp>=3.9", + "PyYAML>=6.0", +] +``` + +```python +# adapter/matrix/agent_registry.py +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + +import yaml + + +class AgentRegistryError(ValueError): + pass + + +@dataclass(frozen=True) +class AgentDefinition: + agent_id: str + label: str + + +class AgentRegistry: + def __init__(self, agents: list[AgentDefinition]) -> None: + self.agents = agents + self._by_id = {agent.agent_id: agent for agent in agents} + + def get(self, agent_id: str) -> AgentDefinition: + try: + return self._by_id[agent_id] + except KeyError as exc: + raise AgentRegistryError(f"unknown agent id: {agent_id}") from exc + + +def load_agent_registry(path: str | Path) -> AgentRegistry: + raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {} + entries = raw.get("agents") + if not isinstance(entries, list) or not entries: + raise AgentRegistryError("agents registry must contain a non-empty agents list") + + agents: list[AgentDefinition] = [] + seen: set[str] = set() + for entry in entries: + agent_id = str(entry.get("id", "")).strip() + label = str(entry.get("label", "")).strip() + if not agent_id or not label: + raise AgentRegistryError("each agent entry requires id and label") + if agent_id in seen: + raise AgentRegistryError(f"duplicate agent id: {agent_id}") + seen.add(agent_id) + agents.append(AgentDefinition(agent_id=agent_id, label=label)) + return AgentRegistry(agents) +``` + +- [ ] **Step 4: Add the example config and runtime wiring docs** + +```yaml +# config/matrix-agents.example.yaml +agents: + - id: agent-1 + label: Analyst + - id: agent-2 + label: Research +``` + +```env +# .env.example +MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml +``` + +```markdown +# README.md +1. Copy `config/matrix-agents.example.yaml` to `config/matrix-agents.yaml` +2. Set `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` +3. Use `!agent` in Matrix to select the active upstream agent +``` + +- [ ] **Step 5: Run the registry tests to verify they pass** + +Run: `uv run pytest tests/adapter/matrix/test_agent_registry.py -q` + +Expected: PASS + +- [ ] **Step 6: Commit** + +```bash +git add pyproject.toml .env.example README.md config/matrix-agents.example.yaml adapter/matrix/agent_registry.py tests/adapter/matrix/test_agent_registry.py +git commit -m "feat: add matrix agent registry loader" +``` + +--- + +### Task 2: Add A Matrix Routing Facade Without Changing `PlatformClient` + +**Files:** +- Create: `adapter/matrix/routed_platform.py` +- Create: `tests/adapter/matrix/test_routed_platform.py` +- Modify: `adapter/matrix/bot.py` + +- [ ] **Step 1: Write the failing routed-platform tests** + +```python +# tests/adapter/matrix/test_routed_platform.py +import pytest + +from adapter.matrix.routed_platform import RoutedPlatformClient +from adapter.matrix.store import set_room_meta +from core.chat import ChatManager +from core.store import InMemoryStore +from sdk.interface import MessageResponse +from sdk.prototype_state import PrototypeStateStore + + +class FakeDelegate: + def __init__(self, agent_id: str) -> None: + self.agent_id = agent_id + self.calls = [] + + async def send_message(self, user_id: str, chat_id: str, text: str, attachments=None): + self.calls.append((user_id, chat_id, text, attachments)) + return MessageResponse( + message_id=user_id, + response=f"{self.agent_id}:{text}", + tokens_used=0, + finished=True, + ) + + async def get_or_create_user(self, external_id: str, platform: str, display_name=None): + return await PrototypeStateStore().get_or_create_user(external_id, platform, display_name) + + async def get_settings(self, user_id: str): + return await PrototypeStateStore().get_settings(user_id) + + async def update_settings(self, user_id: str, action): + return None + + +@pytest.mark.asyncio +async def test_routed_platform_delegates_using_room_agent_and_platform_chat_id(): + store = InMemoryStore() + chat_mgr = ChatManager(None, store) + await chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org", "Chat 1") + await set_room_meta( + store, + "!room:example.org", + {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41", "agent_id": "agent-2"}, + ) + + delegates = {"agent-2": FakeDelegate("agent-2")} + platform = RoutedPlatformClient(store=store, chat_mgr=chat_mgr, delegates=delegates) + + response = await platform.send_message("u1", "C1", "hello") + + assert response.response == "agent-2:hello" + assert delegates["agent-2"].calls == [("u1", "41", "hello", None)] +``` + +- [ ] **Step 2: Run the routed-platform tests to verify they fail** + +Run: `uv run pytest tests/adapter/matrix/test_routed_platform.py -q` + +Expected: FAIL with `ImportError` for `RoutedPlatformClient`. + +- [ ] **Step 3: Implement the routing facade and integrate runtime construction** + +```python +# adapter/matrix/routed_platform.py +from __future__ import annotations + +from sdk.interface import PlatformClient + + +class RoutedPlatformClient(PlatformClient): + def __init__(self, store, chat_mgr, delegates: dict[str, PlatformClient]) -> None: + self._store = store + self._chat_mgr = chat_mgr + self._delegates = delegates + + async def _resolve_target(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]: + ctx = await self._chat_mgr.get(local_chat_id, user_id=user_id) + if ctx is None: + raise ValueError(f"Chat {local_chat_id} not found for {user_id}") + room_meta = await self._store.get(f"matrix_room:{ctx.surface_ref}") + if room_meta is None or not room_meta.get("agent_id") or not room_meta.get("platform_chat_id"): + raise ValueError(f"Room {ctx.surface_ref} is not bound to an agent target") + delegate = self._delegates[room_meta["agent_id"]] + return delegate, str(room_meta["platform_chat_id"]) + + async def send_message(self, user_id: str, chat_id: str, text: str, attachments=None): + delegate, platform_chat_id = await self._resolve_target(user_id, chat_id) + return await delegate.send_message(user_id, platform_chat_id, text, attachments) + + async def stream_message(self, user_id: str, chat_id: str, text: str, attachments=None): + delegate, platform_chat_id = await self._resolve_target(user_id, chat_id) + async for chunk in delegate.stream_message(user_id, platform_chat_id, text, attachments): + yield chunk + + async def get_or_create_user(self, external_id: str, platform: str, display_name=None): + first_delegate = next(iter(self._delegates.values())) + return await first_delegate.get_or_create_user(external_id, platform, display_name) + + async def get_settings(self, user_id: str): + first_delegate = next(iter(self._delegates.values())) + return await first_delegate.get_settings(user_id) + + async def update_settings(self, user_id: str, action): + first_delegate = next(iter(self._delegates.values())) + await first_delegate.update_settings(user_id, action) +``` + +```python +# adapter/matrix/bot.py +from adapter.matrix.agent_registry import load_agent_registry +from adapter.matrix.routed_platform import RoutedPlatformClient + + +def _build_platform_from_env(store: StateStore, chat_mgr: ChatManager) -> PlatformClient: + backend = os.environ.get("MATRIX_PLATFORM_BACKEND", "mock").strip().lower() + if backend != "real": + return MockPlatformClient() + + registry = load_agent_registry(os.environ["MATRIX_AGENT_REGISTRY_PATH"]) + delegates = { + agent.agent_id: RealPlatformClient( + agent_id=agent.agent_id, + agent_base_url=_agent_base_url_from_env(), + prototype_state=PrototypeStateStore(), + platform="matrix", + ) + for agent in registry.agents + } + return RoutedPlatformClient(store=store, chat_mgr=chat_mgr, delegates=delegates) + + +def build_runtime(...): + store = store or InMemoryStore() + chat_mgr = ChatManager(None, store) + platform = platform or _build_platform_from_env(store, chat_mgr) + auth_mgr = AuthManager(platform, store) + settings_mgr = SettingsManager(platform, store) + dispatcher = EventDispatcher( + platform=platform, + chat_mgr=chat_mgr, + auth_mgr=auth_mgr, + settings_mgr=settings_mgr, + ) +``` + +- [ ] **Step 4: Run the routed-platform tests to verify they pass** + +Run: `uv run pytest tests/adapter/matrix/test_routed_platform.py -q` + +Expected: PASS + +- [ ] **Step 5: Commit** + +```bash +git add adapter/matrix/routed_platform.py adapter/matrix/bot.py tests/adapter/matrix/test_routed_platform.py +git commit -m "feat: add matrix routed platform facade" +``` + +--- + +### Task 3: Add `!agent` Selection And Durable User Agent State + +**Files:** +- Create: `adapter/matrix/handlers/agent.py` +- Create: `tests/adapter/matrix/test_agent_handler.py` +- Modify: `adapter/matrix/store.py` +- Modify: `adapter/matrix/handlers/__init__.py` +- Modify: `adapter/matrix/handlers/settings.py` + +- [ ] **Step 1: Write the failing agent-handler tests** + +```python +# tests/adapter/matrix/test_agent_handler.py +import pytest + +from adapter.matrix.handlers.agent import make_handle_agent +from adapter.matrix.store import get_room_meta, get_selected_agent_id, set_room_meta +from core.protocol import IncomingCommand +from core.store import InMemoryStore + + +class FakeRegistry: + def __init__(self) -> None: + self.agents = [ + type("Agent", (), {"agent_id": "agent-1", "label": "Analyst"})(), + type("Agent", (), {"agent_id": "agent-2", "label": "Research"})(), + ] + + +@pytest.mark.asyncio +async def test_agent_command_lists_available_agents(): + handler = make_handle_agent(store=InMemoryStore(), registry=FakeRegistry()) + result = await handler( + IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="agent", args=[]), + None, + None, + None, + None, + ) + assert "1. Analyst" in result[0].text + assert "2. Research" in result[0].text + + +@pytest.mark.asyncio +async def test_agent_command_persists_selected_agent_and_binds_unbound_room(): + store = InMemoryStore() + await set_room_meta(store, "!room:example.org", {"chat_id": "C1", "matrix_user_id": "u1"}) + handler = make_handle_agent(store=store, registry=FakeRegistry()) + chat_mgr = type( + "ChatMgr", + (), + {"get": staticmethod(lambda chat_id, user_id=None: type("Ctx", (), {"surface_ref": "!room:example.org"})())}, + )() + + await handler( + IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="agent", args=["2"]), + None, + None, + chat_mgr, + None, + ) + + assert await get_selected_agent_id(store, "u1") == "agent-2" + room_meta = await get_room_meta(store, "!room:example.org") + assert room_meta["agent_id"] == "agent-2" +``` + +- [ ] **Step 2: Run the agent-handler tests to verify they fail** + +Run: `uv run pytest tests/adapter/matrix/test_agent_handler.py -q` + +Expected: FAIL with missing handler or store helpers. + +- [ ] **Step 3: Add durable store helpers and implement `!agent`** + +```python +# adapter/matrix/store.py +async def get_selected_agent_id(store: StateStore, matrix_user_id: str) -> str | None: + meta = await get_user_meta(store, matrix_user_id) or {} + value = meta.get("selected_agent_id") + return str(value) if value else None + + +async def set_selected_agent_id(store: StateStore, matrix_user_id: str, agent_id: str) -> None: + meta = await get_user_meta(store, matrix_user_id) or {} + meta["selected_agent_id"] = agent_id + await set_user_meta(store, matrix_user_id, meta) + + +async def set_room_agent_id(store: StateStore, room_id: str, agent_id: str) -> None: + meta = dict(await get_room_meta(store, room_id) or {}) + meta["agent_id"] = agent_id + await set_room_meta(store, room_id, meta) +``` + +```python +# adapter/matrix/handlers/agent.py +from __future__ import annotations + +from adapter.matrix.store import ( + get_room_meta, + get_selected_agent_id, + next_platform_chat_id, + set_platform_chat_id, + set_room_agent_id, + set_selected_agent_id, +) +from core.protocol import IncomingCommand, OutgoingMessage + + +def make_handle_agent(store, registry): + async def handle_agent(event: IncomingCommand, auth_mgr, platform, chat_mgr, settings_mgr): + if not event.args: + current = await get_selected_agent_id(store, event.user_id) + lines = ["Доступные агенты:"] + for index, agent in enumerate(registry.agents, start=1): + marker = " (текущий)" if agent.agent_id == current else "" + lines.append(f"{index}. {agent.label}{marker}") + lines.append("") + lines.append("Выбери агента: !agent <номер>") + return [OutgoingMessage(chat_id=event.chat_id, text="\n".join(lines))] + + agent = registry.agents[int(event.args[0]) - 1] + await set_selected_agent_id(store, event.user_id, agent.agent_id) + ctx = await chat_mgr.get(event.chat_id, user_id=event.user_id) if chat_mgr else None + if ctx is not None: + room_meta = await get_room_meta(store, ctx.surface_ref) + if room_meta is not None and not room_meta.get("agent_id"): + await set_room_agent_id(store, ctx.surface_ref, agent.agent_id) + if not room_meta.get("platform_chat_id"): + await set_platform_chat_id(store, ctx.surface_ref, await next_platform_chat_id(store)) + return [OutgoingMessage(chat_id=event.chat_id, text=f"Агент переключён на {agent.label}. Этот чат готов к работе.")] + return [OutgoingMessage(chat_id=event.chat_id, text=f"Агент переключён на {agent.label}. Для продолжения используй !new.")] + + return handle_agent +``` + +- [ ] **Step 4: Register the command and update help text** + +```python +# adapter/matrix/handlers/__init__.py +from adapter.matrix.handlers.agent import make_handle_agent + +dispatcher.register(IncomingCommand, "agent", make_handle_agent(store, registry)) +``` + +```python +# adapter/matrix/handlers/settings.py +HELP_TEXT = "\n".join( + [ + "Команды", + "", + "!agent выбрать активного агента", + "!new [название] создать новый чат", + "!chats список активных чатов", + "!rename <название> переименовать текущий чат", + "!archive архивировать текущий чат", + "!context показать текущее состояние контекста", + "!save [имя] сохранить текущий контекст", + "!load показать сохранённые контексты", + ] +) +``` + +- [ ] **Step 5: Run the agent-handler tests to verify they pass** + +Run: `uv run pytest tests/adapter/matrix/test_agent_handler.py -q` + +Expected: PASS + +- [ ] **Step 6: Commit** + +```bash +git add adapter/matrix/store.py adapter/matrix/handlers/agent.py adapter/matrix/handlers/__init__.py adapter/matrix/handlers/settings.py tests/adapter/matrix/test_agent_handler.py +git commit -m "feat: add matrix agent selection command" +``` + +--- + +### Task 4: Bind Rooms Correctly And Block Stale Chats + +**Files:** +- Modify: `adapter/matrix/bot.py` +- Modify: `adapter/matrix/handlers/chat.py` +- Modify: `adapter/matrix/handlers/context_commands.py` +- Modify: `tests/adapter/matrix/test_dispatcher.py` +- Modify: `tests/adapter/matrix/test_context_commands.py` + +- [ ] **Step 1: Write the failing dispatcher and context-command tests** + +```python +# tests/adapter/matrix/test_dispatcher.py +@pytest.mark.asyncio +async def test_bot_replies_with_agent_prompt_when_user_has_no_selected_agent(): + runtime = build_runtime(platform=MockPlatformClient()) + client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock()) + bot = MatrixBot(client, runtime) + await set_room_meta(runtime.store, "!room:example.org", {"chat_id": "C1", "matrix_user_id": "@alice:example.org"}) + + await bot.on_room_message(SimpleNamespace(room_id="!room:example.org"), SimpleNamespace(sender="@alice:example.org", body="hello")) + + client.room_send.assert_awaited_once() + assert "выбери агента" in client.room_send.call_args.args[2]["body"].lower() + + +@pytest.mark.asyncio +async def test_new_chat_requires_selected_agent_and_binds_room_meta(): + client = SimpleNamespace( + room_create=AsyncMock(return_value=SimpleNamespace(room_id="!r2:example")), + room_put_state=AsyncMock(), + ) + runtime = build_runtime(platform=MockPlatformClient(), client=client) + await set_user_meta(runtime.store, "u1", {"space_id": "!space:example", "next_chat_index": 2, "selected_agent_id": "agent-2"}) + + result = await runtime.dispatcher.dispatch( + IncomingCommand(user_id="u1", platform="matrix", chat_id="C1", command="new", args=["Research"]) + ) + + room_meta = await get_room_meta(runtime.store, "!r2:example") + assert room_meta["agent_id"] == "agent-2" + assert "Создан чат" in result[0].text +``` + +```python +# tests/adapter/matrix/test_context_commands.py +@pytest.mark.asyncio +async def test_load_selection_calls_platform_with_local_chat_id(): + platform = MatrixCommandPlatform() + runtime = build_runtime(platform=platform) + await runtime.chat_mgr.get_or_create("u1", "C1", "matrix", "!room:example.org", "Chat 1") + await set_room_meta(runtime.store, "!room:example.org", {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41", "agent_id": "agent-2"}) + + client = SimpleNamespace(user_id="@bot:example.org", room_send=AsyncMock()) + bot = MatrixBot(client, runtime) + await set_load_pending(runtime.store, "u1", "!room:example.org", {"saves": [{"name": "session-a", "created_at": "2026-04-17T00:00:00+00:00"}]}) + + await bot.on_room_message(SimpleNamespace(room_id="!room:example.org"), SimpleNamespace(sender="u1", body="1")) + + platform.send_message.assert_awaited_once_with("u1", "C1", LOAD_PROMPT.format(name="session-a")) +``` + +- [ ] **Step 2: Run the dispatcher and context-command tests to verify they fail** + +Run: `uv run pytest tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py -q` + +Expected: FAIL because the current runtime still injects `platform_chat_id` into normal messages and `!new` does not require or persist `agent_id`. + +- [ ] **Step 3: Implement room binding and stale-room checks in runtime** + +```python +# adapter/matrix/bot.py +from adapter.matrix.store import ( + get_selected_agent_id, + get_room_meta, + next_platform_chat_id, + set_platform_chat_id, + set_room_agent_id, +) + + +async def _ensure_active_room_target(self, room_id: str, user_id: str) -> tuple[dict | None, OutgoingMessage | None]: + room_meta = await get_room_meta(self.runtime.store, room_id) + selected_agent_id = await get_selected_agent_id(self.runtime.store, user_id) + if not selected_agent_id: + return room_meta, OutgoingMessage(chat_id=room_id, text="Сначала выбери агента через !agent.") + if room_meta is None: + return room_meta, None + if not room_meta.get("agent_id"): + await set_room_agent_id(self.runtime.store, room_id, selected_agent_id) + if not room_meta.get("platform_chat_id"): + await set_platform_chat_id(self.runtime.store, room_id, await next_platform_chat_id(self.runtime.store)) + room_meta = await get_room_meta(self.runtime.store, room_id) + return room_meta, None + if room_meta["agent_id"] != selected_agent_id: + return room_meta, OutgoingMessage(chat_id=room_id, text="Этот чат привязан к старому агенту. Используй !new.") + return room_meta, None +``` + +```python +# adapter/matrix/bot.py +local_chat_id = await resolve_chat_id(self.runtime.store, room.room_id, sender) +dispatch_chat_id = local_chat_id + +if not body.startswith("!"): + room_meta, blocking = await self._ensure_active_room_target(room.room_id, sender) + if blocking is not None: + await self._send_all(room.room_id, [blocking]) + return + +incoming = from_room_event(event, room_id=room.room_id, chat_id=dispatch_chat_id) +``` + +- [ ] **Step 4: Require selected agent for `!new` and persist room `agent_id`** + +```python +# adapter/matrix/handlers/chat.py +from adapter.matrix.store import get_selected_agent_id + +selected_agent_id = await get_selected_agent_id(store, event.user_id) +if not selected_agent_id: + return [OutgoingMessage(chat_id=event.chat_id, text="Сначала выбери агента через !agent.")] + +await set_room_meta( + store, + room_id, + { + "room_type": "chat", + "chat_id": chat_id, + "display_name": room_name, + "matrix_user_id": event.user_id, + "space_id": space_id, + "platform_chat_id": platform_chat_id, + "agent_id": selected_agent_id, + }, +) +``` + +```python +# adapter/matrix/bot.py +room_meta = await get_room_meta(self.runtime.store, room_id) +local_chat_id = room_meta.get("chat_id", room_id) if room_meta else room_id + +await self.runtime.platform.send_message( + user_id, + local_chat_id, + LOAD_PROMPT.format(name=name), +) +``` + +- [ ] **Step 5: Run the dispatcher and context-command tests to verify they pass** + +Run: `uv run pytest tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py -q` + +Expected: PASS + +- [ ] **Step 6: Commit** + +```bash +git add adapter/matrix/bot.py adapter/matrix/handlers/chat.py adapter/matrix/handlers/context_commands.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py +git commit -m "feat: bind matrix rooms to selected agents" +``` + +--- + +### Task 5: Prove Durable Restart State And Sequence Persistence + +**Files:** +- Create: `tests/adapter/matrix/test_restart_persistence.py` +- Modify: `adapter/matrix/store.py` +- Modify: `README.md` + +- [ ] **Step 1: Write the failing restart-persistence tests** + +```python +# tests/adapter/matrix/test_restart_persistence.py +import pytest + +from adapter.matrix.store import ( + get_selected_agent_id, + next_platform_chat_id, + set_room_meta, + set_selected_agent_id, +) +from core.store import SQLiteStore + + +@pytest.mark.asyncio +async def test_selected_agent_and_room_binding_survive_store_recreation(tmp_path): + db_path = tmp_path / "matrix.db" + store = SQLiteStore(str(db_path)) + await set_selected_agent_id(store, "u1", "agent-2") + await set_room_meta( + store, + "!room:example.org", + {"chat_id": "C1", "matrix_user_id": "u1", "platform_chat_id": "41", "agent_id": "agent-2"}, + ) + + reopened = SQLiteStore(str(db_path)) + assert await get_selected_agent_id(reopened, "u1") == "agent-2" + assert (await reopened.get("matrix_room:!room:example.org"))["agent_id"] == "agent-2" + assert (await reopened.get("matrix_room:!room:example.org"))["platform_chat_id"] == "41" + + +@pytest.mark.asyncio +async def test_platform_chat_sequence_survives_store_recreation(tmp_path): + db_path = tmp_path / "matrix.db" + store = SQLiteStore(str(db_path)) + + assert await next_platform_chat_id(store) == "1" + assert await next_platform_chat_id(store) == "2" + + reopened = SQLiteStore(str(db_path)) + assert await next_platform_chat_id(reopened) == "3" +``` + +- [ ] **Step 2: Run the restart-persistence tests to verify they fail** + +Run: `uv run pytest tests/adapter/matrix/test_restart_persistence.py -q` + +Expected: FAIL because `selected_agent_id` helpers do not exist yet or sequence persistence behavior is not explicitly covered. + +- [ ] **Step 3: Make sequence persistence explicit and document the restart boundary** + +```python +# adapter/matrix/store.py +PLATFORM_CHAT_SEQ_KEY = "matrix_platform_chat_seq" + + +async def next_platform_chat_id(store: StateStore) -> str: + async with _PLATFORM_CHAT_SEQ_LOCK: + data = await store.get(PLATFORM_CHAT_SEQ_KEY) + index = int((data or {}).get("next_platform_chat_index", 1)) + await store.set(PLATFORM_CHAT_SEQ_KEY, {"next_platform_chat_index": index + 1}) + return str(index) +``` + +```markdown +# README.md +- Matrix durable state lives in `lambda_matrix.db` and `matrix_store` +- normal restart is supported only when those paths survive container recreation +- staged attachments and pending confirmations are intentionally not restored +``` + +- [ ] **Step 4: Run the restart-persistence tests to verify they pass** + +Run: `uv run pytest tests/adapter/matrix/test_restart_persistence.py -q` + +Expected: PASS + +- [ ] **Step 5: Run the combined verification sweep** + +Run: `uv run pytest tests/adapter/matrix/test_agent_registry.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_agent_handler.py tests/adapter/matrix/test_dispatcher.py tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_restart_persistence.py tests/platform/test_real.py -q` + +Expected: PASS + +- [ ] **Step 6: Commit** + +```bash +git add adapter/matrix/store.py README.md tests/adapter/matrix/test_restart_persistence.py +git commit -m "test: cover matrix restart state persistence" +``` + +--- + +## Self-Review + +### Spec coverage + +- Multi-agent agent registry: Task 1 +- Shared `PlatformClient` preserved via routing facade: Task 2 +- `!agent` UX and durable `selected_agent_id`: Task 3 +- Unbound room activation, `!new`, stale room rejection: Task 4 +- Restart durability for user state, room state, and `PLATFORM_CHAT_SEQ_KEY`: Task 5 + +### Placeholder scan + +- No `TODO`, `TBD`, or “implement later” markers remain. +- Each task includes exact file paths, tests, commands, and minimal code snippets. + +### Type consistency + +- `selected_agent_id` lives in user metadata throughout the plan. +- `agent_id` and `platform_chat_id` live in room metadata throughout the plan. +- `RoutedPlatformClient` keeps the existing `PlatformClient` method names intact. diff --git a/sdk/real.py b/sdk/real.py index bf432d9..47f639a 100644 --- a/sdk/real.py +++ b/sdk/real.py @@ -1,8 +1,11 @@ from __future__ import annotations import asyncio +import os +import re from collections.abc import AsyncIterator from pathlib import Path +from urllib.parse import urljoin, urlsplit, urlunsplit import structlog @@ -21,6 +24,11 @@ from sdk.upstream_agent_api import AgentApi, MsgEventSendFile, MsgEventTextChunk logger = structlog.get_logger(__name__) +def _ws_debug_enabled() -> bool: + value = os.environ.get("SURFACES_DEBUG_WS", "") + return value.strip().lower() in {"1", "true", "yes", "on"} + + class RealPlatformClient(PlatformClient): def __init__( self, @@ -31,11 +39,20 @@ class RealPlatformClient(PlatformClient): agent_api_cls=AgentApi, ) -> None: self._agent_id = agent_id - self._agent_base_url = agent_base_url + self._raw_agent_base_url = agent_base_url + self._agent_base_url = self._normalize_agent_base_url(agent_base_url) self._agent_api_cls = agent_api_cls self._prototype_state = prototype_state self._platform = platform self._chat_send_locks: dict[str, asyncio.Lock] = {} + if _ws_debug_enabled(): + logger.warning( + "agent_client_initialized", + agent_id=self._agent_id, + platform=self._platform, + raw_base_url=self._raw_agent_base_url, + normalized_base_url=self._agent_base_url, + ) @property def agent_id(self) -> str: @@ -171,12 +188,28 @@ class RealPlatformClient(PlatformClient): yield event def _build_chat_api(self, chat_id: str): + if _ws_debug_enabled(): + logger.warning( + "agent_chat_api_build", + agent_id=self._agent_id, + chat_id=str(chat_id), + normalized_base_url=self._agent_base_url, + ws_url=urljoin(self._agent_base_url, f"v1/agent_ws/{chat_id}/"), + ) return self._agent_api_cls( agent_id=self._agent_id, base_url=self._agent_base_url, chat_id=str(chat_id), ) + @staticmethod + def _normalize_agent_base_url(base_url: str) -> str: + parsed = urlsplit(base_url) + path = re.sub(r"(?:/v1)?/agent_ws(?:/[^/]+)?/?$", "", parsed.path.rstrip("/")) + if path: + path = f"{path}/" + return urlunsplit((parsed.scheme, parsed.netloc, path, "", "")) + @staticmethod async def _close_chat_api(chat_api) -> None: close = getattr(chat_api, "close", None) diff --git a/telegram-cloud-photo-size-2-5440546240941724952-y.jpg b/telegram-cloud-photo-size-2-5440546240941724952-y.jpg new file mode 100644 index 0000000000000000000000000000000000000000..af4606de24af0191341926ad42636478ec33baac GIT binary patch literal 49274 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%0D`bJWXRw}OUdyaS^ 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 literal 0 HcmV?d00001 diff --git a/tests/adapter/matrix/test_dispatcher.py b/tests/adapter/matrix/test_dispatcher.py index 1733b75..1240f86 100644 --- a/tests/adapter/matrix/test_dispatcher.py +++ b/tests/adapter/matrix/test_dispatcher.py @@ -211,7 +211,7 @@ async def test_invite_event_is_idempotent_per_user(): assert client.join.await_count == 2 assert client.room_create.await_count == 2 - client.room_send.assert_awaited_once() + assert client.room_send.await_count == 2 async def test_bot_ignores_its_own_messages(): @@ -348,7 +348,8 @@ async def test_bot_downloads_matrix_file_to_configured_agent_workspace(tmp_path, base_url="http://lambda.coredump.ru:7000/agent_17/", workspace_path=str(tmp_path / "agents" / "17"), ) - ] + ], + user_agents={"@alice:example.org": "agent-17"}, ) await set_room_meta( runtime.store, @@ -381,7 +382,7 @@ async def test_bot_downloads_matrix_file_to_configured_agent_workspace(tmp_path, staged = await get_staged_attachments( runtime.store, "!chat17:example.org", "@alice:example.org" ) - assert staged[0]["workspace_path"].startswith("incoming/") + assert staged[0]["workspace_path"] == "report.pdf" assert ( tmp_path / "agents" / "17" / staged[0]["workspace_path"] ).read_bytes() == b"%PDF-1.7" @@ -389,7 +390,7 @@ async def test_bot_downloads_matrix_file_to_configured_agent_workspace(tmp_path, async def test_bot_uploads_agent_output_from_configured_agent_workspace(tmp_path, monkeypatch): monkeypatch.setenv("SURFACES_WORKSPACE_DIR", str(tmp_path / "agents")) - output_file = tmp_path / "agents" / "17" / "output" / "result.txt" + output_file = tmp_path / "agents" / "17" / "result.txt" output_file.parent.mkdir(parents=True) output_file.write_text("ready", encoding="utf-8") runtime = build_runtime(platform=MockPlatformClient()) @@ -401,7 +402,8 @@ async def test_bot_uploads_agent_output_from_configured_agent_workspace(tmp_path base_url="http://lambda.coredump.ru:7000/agent_17/", workspace_path=str(tmp_path / "agents" / "17"), ) - ] + ], + user_agents={"@alice:example.org": "agent-17"}, ) await set_room_meta( runtime.store, @@ -429,7 +431,7 @@ async def test_bot_uploads_agent_output_from_configured_agent_workspace(tmp_path type="document", filename="result.txt", mime_type="text/plain", - workspace_path="output/result.txt", + workspace_path="result.txt", ) ], ) diff --git a/tests/adapter/matrix/test_files.py b/tests/adapter/matrix/test_files.py index 674907d..a3a9146 100644 --- a/tests/adapter/matrix/test_files.py +++ b/tests/adapter/matrix/test_files.py @@ -4,29 +4,12 @@ from pathlib import Path from types import SimpleNamespace from adapter.matrix.files import ( - build_agent_incoming_path, - build_workspace_attachment_path, + build_agent_workspace_path, download_matrix_attachment, ) from core.protocol import Attachment -def test_build_workspace_attachment_path_scopes_by_surface_user_and_room(tmp_path: Path): - rel_path, abs_path = build_workspace_attachment_path( - workspace_root=tmp_path, - matrix_user_id="@alice:example.org", - room_id="!room:example.org", - filename="report.pdf", - timestamp="20260420-153000", - ) - - assert ( - rel_path - == "surfaces/matrix/alice_example.org/room_example.org/inbox/20260420-153000-report.pdf" - ) - assert abs_path == tmp_path / rel_path - - async def test_download_matrix_attachment_persists_file_and_returns_workspace_path(tmp_path: Path): async def download(url: str): assert url == "mxc://server/id" @@ -49,40 +32,46 @@ async def test_download_matrix_attachment_persists_file_and_returns_workspace_pa timestamp="20260420-153000", ) - assert saved.workspace_path is not None - assert saved.workspace_path.endswith("20260420-153000-report.pdf") - assert (tmp_path / saved.workspace_path).read_bytes() == b"%PDF-1.7" + assert saved.workspace_path == "report.pdf" + assert (tmp_path / "report.pdf").read_bytes() == b"%PDF-1.7" -def test_build_workspace_attachment_path_keeps_room_safe_agents_relative_contract(tmp_path: Path): - rel_path, abs_path = build_workspace_attachment_path( - workspace_root=tmp_path / "agents" / "7", - matrix_user_id="@alice+bob:example.org", - room_id="!room/ops:example.org", - filename="quarterly status (final).pdf", - timestamp="20260420-153000", - ) - - assert rel_path == ( - "surfaces/matrix/alice_bob_example.org/room_ops_example.org/inbox/" - "20260420-153000-quarterly_status_final_.pdf" - ) - assert not Path(rel_path).is_absolute() - assert abs_path == tmp_path / "agents" / "7" / rel_path - - -def test_build_agent_incoming_path_uses_agent_workspace_volume(tmp_path: Path): - rel_path, abs_path = build_agent_incoming_path( +def test_build_agent_workspace_path_uses_agent_workspace_volume(tmp_path: Path): + rel_path, abs_path = build_agent_workspace_path( workspace_root=tmp_path / "agents" / "17", filename="quarterly status.pdf", - timestamp="20260428-110000", ) - assert rel_path == "incoming/20260428-110000-quarterly_status.pdf" + assert rel_path == "quarterly status.pdf" assert abs_path == tmp_path / "agents" / "17" / rel_path -async def test_download_matrix_attachment_uses_agent_workspace_incoming_dir(tmp_path: Path): +def test_build_agent_workspace_path_uses_windows_style_copy_index(tmp_path: Path): + workspace_root = tmp_path / "agents" / "17" + workspace_root.mkdir(parents=True) + (workspace_root / "report.pdf").write_bytes(b"old") + (workspace_root / "report (1).pdf").write_bytes(b"older") + + rel_path, abs_path = build_agent_workspace_path( + workspace_root=workspace_root, + filename="report.pdf", + ) + + assert rel_path == "report (2).pdf" + assert abs_path == workspace_root / "report (2).pdf" + + +def test_build_agent_workspace_path_sanitizes_to_basename(tmp_path: Path): + rel_path, abs_path = build_agent_workspace_path( + workspace_root=tmp_path / "agents" / "17", + filename="../../quarterly: status?.pdf", + ) + + assert rel_path == "quarterly_ status_.pdf" + assert abs_path == tmp_path / "agents" / "17" / "quarterly_ status_.pdf" + + +async def test_download_matrix_attachment_uses_agent_workspace_root(tmp_path: Path): async def download(url: str): assert url == "mxc://server/id" return SimpleNamespace(body=b"%PDF-1.7") @@ -101,5 +90,5 @@ async def test_download_matrix_attachment_uses_agent_workspace_incoming_dir(tmp_ timestamp="20260428-110000", ) - assert saved.workspace_path == "incoming/20260428-110000-report.pdf" + assert saved.workspace_path == "report.pdf" assert (tmp_path / "agents" / "17" / saved.workspace_path).read_bytes() == b"%PDF-1.7" diff --git a/tests/adapter/matrix/test_invite_space.py b/tests/adapter/matrix/test_invite_space.py index 52f8335..15ca57c 100644 --- a/tests/adapter/matrix/test_invite_space.py +++ b/tests/adapter/matrix/test_invite_space.py @@ -7,7 +7,7 @@ from nio.api import RoomVisibility from adapter.matrix.bot import build_runtime from adapter.matrix.handlers.auth import handle_invite -from adapter.matrix.store import get_room_meta, get_user_meta, set_user_meta +from adapter.matrix.store import get_room_meta, get_user_meta, set_room_meta, set_user_meta from sdk.mock import MockPlatformClient @@ -100,6 +100,53 @@ async def test_mat02_invite_idempotent(): assert client.room_create.await_count == 2 +async def test_existing_user_invite_reinvites_space_and_active_chats(): + runtime = build_runtime(platform=MockPlatformClient()) + await set_user_meta( + runtime.store, + "@alice:example.org", + {"space_id": "!space:example.org", "next_chat_index": 2}, + ) + await set_room_meta( + runtime.store, + "!chat1:example.org", + { + "room_type": "chat", + "chat_id": "C1", + "display_name": "Чат 1", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + "platform_chat_id": "1", + "agent_id": "agent-1", + }, + ) + await runtime.chat_mgr.get_or_create( + user_id="@alice:example.org", + chat_id="C1", + platform="matrix", + surface_ref="!chat1:example.org", + name="Чат 1", + ) + client = _make_client() + room = SimpleNamespace(room_id="!dm:example.org", display_name="Alice") + event = SimpleNamespace(sender="@alice:example.org", membership="invite") + + await handle_invite( + client, + room, + event, + runtime.platform, + runtime.store, + runtime.auth_mgr, + runtime.chat_mgr, + ) + + client.room_create.assert_not_awaited() + client.room_invite.assert_any_await("!space:example.org", "@alice:example.org") + client.room_invite.assert_any_await("!chat1:example.org", "@alice:example.org") + client.room_send.assert_awaited() + + async def test_mat03_no_hardcoded_c1(): runtime = build_runtime(platform=MockPlatformClient()) await set_user_meta(runtime.store, "@alice:example.org", {"next_chat_index": 7}) diff --git a/tests/adapter/matrix/test_reconciliation.py b/tests/adapter/matrix/test_reconciliation.py index 3732bbc..c44ffc0 100644 --- a/tests/adapter/matrix/test_reconciliation.py +++ b/tests/adapter/matrix/test_reconciliation.py @@ -4,6 +4,7 @@ import importlib from types import SimpleNamespace from unittest.mock import AsyncMock +from adapter.matrix.agent_registry import AgentDefinition, AgentRegistry from adapter.matrix.bot import MatrixBot, build_runtime from adapter.matrix.reconciliation import reconcile_startup_state from adapter.matrix.store import get_room_meta, get_user_meta, set_room_meta, set_user_meta @@ -124,6 +125,55 @@ async def test_reconcile_startup_state_is_idempotent_with_existing_local_state() assert chats[0].chat_id == "C3" +async def test_reconcile_updates_default_agent_assignment_after_user_is_configured(): + runtime = build_runtime(platform=MockPlatformClient()) + runtime.registry = AgentRegistry( + [ + AgentDefinition("agent-default", "Default"), + AgentDefinition("agent-alice", "Alice"), + ], + user_agents={"@alice:example.org": "agent-alice"}, + ) + client = SimpleNamespace( + user_id="@bot:example.org", + rooms={ + "!space:example.org": _room( + "!space:example.org", + "Lambda - Alice", + ["@bot:example.org", "@alice:example.org"], + ), + "!chat3:example.org": _room( + "!chat3:example.org", + "Чат 3", + ["@bot:example.org", "@alice:example.org"], + parents=("!space:example.org",), + ), + }, + ) + await set_room_meta( + runtime.store, + "!chat3:example.org", + { + "room_type": "chat", + "chat_id": "C3", + "display_name": "Чат 3", + "matrix_user_id": "@alice:example.org", + "space_id": "!space:example.org", + "platform_chat_id": "42", + "agent_id": "agent-default", + "agent_assignment": "default", + }, + ) + + await reconcile_startup_state(client, runtime) + + room_meta = await get_room_meta(runtime.store, "!chat3:example.org") + assert room_meta is not None + assert room_meta["agent_id"] == "agent-alice" + assert room_meta["agent_assignment"] == "configured" + assert room_meta["platform_chat_id"] == "42" + + async def test_reconciliation_prevents_lazy_bootstrap_for_existing_room(): runtime = build_runtime(platform=MockPlatformClient()) client = SimpleNamespace( diff --git a/tests/platform/test_real.py b/tests/platform/test_real.py index 81a73b2..8bce30b 100644 --- a/tests/platform/test_real.py +++ b/tests/platform/test_real.py @@ -185,6 +185,24 @@ async def test_real_platform_client_send_message_uses_direct_agent_api_per_chat( assert await prototype_state.get_last_tokens_used_for_context("chat-7") == 0 +@pytest.mark.asyncio +async def test_real_platform_client_preserves_path_base_url_without_trailing_slash(): + agent_api = FakeAgentApiFactory() + client = RealPlatformClient( + agent_id="agent-17", + agent_base_url="http://lambda.coredump.ru:7000/agent_17", + agent_api_cls=agent_api, + prototype_state=PrototypeStateStore(), + platform="matrix", + ) + + await client.send_message("@alice:example.org", "41", "hello") + + assert agent_api.created_calls == [ + ("agent-17", "http://lambda.coredump.ru:7000/agent_17/", "41") + ] + + @pytest.mark.asyncio async def test_real_platform_client_forwards_attachments_to_chat_api(): agent_api = FakeAgentApiFactory(chat_api_cls=AttachmentTrackingChatAgentApi) @@ -213,15 +231,15 @@ async def test_real_platform_client_forwards_attachments_to_chat_api(): def test_attachment_paths_normalize_workspace_roots_to_relative_paths(): attachments = [ - Attachment(workspace_path="/workspace/output/report.pdf"), - Attachment(workspace_path="/agents/7/output/report.csv"), - Attachment(workspace_path="surfaces/matrix/alice/room/inbox/note.txt"), + Attachment(workspace_path="/workspace/report.pdf"), + Attachment(workspace_path="/agents/7/report.csv"), + Attachment(workspace_path="note.txt"), ] assert RealPlatformClient._attachment_paths(attachments) == [ - "output/report.pdf", - "output/report.csv", - "surfaces/matrix/alice/room/inbox/note.txt", + "report.pdf", + "report.csv", + "note.txt", ] @@ -257,9 +275,12 @@ async def test_real_platform_client_preserves_send_file_events_in_sync_result(mo @pytest.mark.parametrize( ("location", "expected_workspace_path"), [ - ("/workspace/output/report.pdf", "output/report.pdf"), - ("/agents/7/output/report.pdf", "output/report.pdf"), - ("surfaces/matrix/alice/room/inbox/report.pdf", "surfaces/matrix/alice/room/inbox/report.pdf"), + ("/workspace/report.pdf", "report.pdf"), + ("/agents/7/report.pdf", "report.pdf"), + ( + "surfaces/matrix/alice/room/inbox/report.pdf", + "surfaces/matrix/alice/room/inbox/report.pdf", + ), ], ) def test_attachment_from_send_file_event_normalizes_shared_volume_paths( diff --git a/tests/test_check_matrix_agents.py b/tests/test_check_matrix_agents.py new file mode 100644 index 0000000..25f63bd --- /dev/null +++ b/tests/test_check_matrix_agents.py @@ -0,0 +1,22 @@ +from tools.check_matrix_agents import build_agent_ws_url + + +def test_build_agent_ws_url_preserves_path_prefix_without_trailing_slash(): + assert ( + build_agent_ws_url("http://lambda.coredump.ru:7000/agent_17", "41") + == "http://lambda.coredump.ru:7000/agent_17/v1/agent_ws/41/" + ) + + +def test_build_agent_ws_url_preserves_path_prefix_with_trailing_slash(): + assert ( + build_agent_ws_url("http://lambda.coredump.ru:7000/agent_17/", "41") + == "http://lambda.coredump.ru:7000/agent_17/v1/agent_ws/41/" + ) + + +def test_build_agent_ws_url_accepts_existing_agent_ws_url(): + assert ( + build_agent_ws_url("http://lambda.coredump.ru:7000/agent_17/v1/agent_ws/0/", "41") + == "http://lambda.coredump.ru:7000/agent_17/v1/agent_ws/41/" + ) diff --git a/tests/test_deploy_handoff.py b/tests/test_deploy_handoff.py index e2f3953..0cf2057 100644 --- a/tests/test_deploy_handoff.py +++ b/tests/test_deploy_handoff.py @@ -39,6 +39,21 @@ def test_dockerfile_production_build_does_not_require_local_external_tree(): assert "uv pip install --system --ignore-requires-python" not in dockerfile +def test_dockerfile_installs_agent_api_after_final_uv_sync(): + dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8") + development = dockerfile.split("FROM base AS development", maxsplit=1)[1].split( + "FROM base AS production", maxsplit=1 + )[0] + production = dockerfile.split("FROM base AS production", maxsplit=1)[1] + + assert development.index("RUN uv sync --no-dev --frozen") < development.index( + "pip install --no-cache-dir --ignore-requires-python -e /agent_api/" + ) + assert production.index("RUN uv sync --no-dev --frozen") < production.index( + "git+https://git.lambda.coredump.ru/platform/agent_api.git" + ) + + def test_dockerignore_excludes_local_only_and_runtime_artifacts(): dockerignore = (ROOT / ".dockerignore").read_text(encoding="utf-8") @@ -60,3 +75,28 @@ def test_agent_registry_example_documents_multi_agent_volume_contract(): for index, agent in enumerate(agents): assert agent["base_url"].endswith(f"/agent_{index}/") assert agent["workspace_path"] == f"/agents/{index}" + + +def test_smoke_compose_models_deploy_like_proxy_and_surface_checker(): + smoke = _compose("docker-compose.smoke.yml") + + assert set(smoke["services"]) >= {"surface-smoke", "agent-proxy", "agent-0", "agent-1"} + assert "tools.check_matrix_agents" in smoke["services"]["surface-smoke"]["command"] + assert smoke["services"]["agent-proxy"]["ports"] == ["${SMOKE_PROXY_PORT:-7000}:7000"] + + +def test_smoke_timeout_override_routes_one_agent_to_no_status_stub(): + smoke_timeout = _compose("docker-compose.smoke.timeout.yml") + + assert set(smoke_timeout["services"]) >= {"agent-proxy", "agent-no-status"} + + +def test_smoke_registry_targets_local_proxy_routes(): + registry = yaml.safe_load( + (ROOT / "config" / "matrix-agents.smoke.yaml").read_text(encoding="utf-8") + ) + + assert [agent["base_url"] for agent in registry["agents"]] == [ + "http://agent-proxy:7000/agent_0/", + "http://agent-proxy:7000/agent_1/", + ] diff --git a/tools/__init__.py b/tools/__init__.py new file mode 100644 index 0000000..a1d9c25 --- /dev/null +++ b/tools/__init__.py @@ -0,0 +1 @@ +"""Operational tools for surfaces-bot.""" diff --git a/tools/check_matrix_agents.py b/tools/check_matrix_agents.py new file mode 100644 index 0000000..d6035aa --- /dev/null +++ b/tools/check_matrix_agents.py @@ -0,0 +1,197 @@ +from __future__ import annotations + +import argparse +import asyncio +import json +import os +import time +from dataclasses import asdict, dataclass +from pathlib import Path +from urllib.parse import urljoin + +import aiohttp + +from adapter.matrix.agent_registry import AgentDefinition, load_agent_registry +from sdk.real import RealPlatformClient + + +@dataclass +class AgentCheckResult: + agent_id: str + label: str + chat_id: str + base_url: str + ws_url: str + ok: bool + stage: str + latency_ms: int + error: str = "" + response_type: str = "" + + +def build_agent_ws_url(base_url: str, chat_id: str) -> str: + normalized = RealPlatformClient._normalize_agent_base_url(base_url) + return urljoin(normalized, f"v1/agent_ws/{chat_id}/") + + +def _message_type(payload: str) -> str: + try: + data = json.loads(payload) + except json.JSONDecodeError: + return "" + value = data.get("type") + return value if isinstance(value, str) else "" + + +async def _receive_text(ws: aiohttp.ClientWebSocketResponse, timeout: float) -> str: + msg = await asyncio.wait_for(ws.receive(), timeout=timeout) + if msg.type == aiohttp.WSMsgType.TEXT: + return str(msg.data) + if msg.type == aiohttp.WSMsgType.ERROR: + raise RuntimeError(f"websocket error: {ws.exception()}") + raise RuntimeError(f"unexpected websocket message type: {msg.type.name}") + + +async def check_agent( + agent: AgentDefinition, + *, + fallback_base_url: str, + chat_id: str, + timeout: float, + message: str | None, +) -> AgentCheckResult: + base_url = agent.base_url or fallback_base_url + ws_url = build_agent_ws_url(base_url, chat_id) if base_url else "" + started = time.perf_counter() + + def result(ok: bool, stage: str, error: str = "", response_type: str = "") -> AgentCheckResult: + return AgentCheckResult( + agent_id=agent.agent_id, + label=agent.label, + chat_id=chat_id, + base_url=base_url, + ws_url=ws_url, + ok=ok, + stage=stage, + latency_ms=int((time.perf_counter() - started) * 1000), + error=error, + response_type=response_type, + ) + + if not base_url: + return result(False, "config", "missing base_url and AGENT_BASE_URL") + + try: + client_timeout = aiohttp.ClientTimeout( + total=timeout, + connect=timeout, + sock_connect=timeout, + sock_read=timeout, + ) + async with aiohttp.ClientSession(timeout=client_timeout) as session: + async with session.ws_connect(ws_url, heartbeat=30) as ws: + raw_status = await _receive_text(ws, timeout) + status_type = _message_type(raw_status) + if status_type != "STATUS": + return result( + False, + "status", + f"expected STATUS, got {raw_status[:200]}", + status_type, + ) + + if not message: + return result(True, "status", response_type=status_type) + + payload = { + "type": "USER_MESSAGE", + "text": message, + "attachments": [], + } + await ws.send_str(json.dumps(payload)) + + while True: + raw_event = await _receive_text(ws, timeout) + event_type = _message_type(raw_event) + if event_type == "ERROR": + return result(False, "message", raw_event[:200], event_type) + if event_type == "AGENT_EVENT_END": + return result(True, "message", response_type=event_type) + if not event_type: + return result(False, "message", f"invalid JSON event: {raw_event[:200]}") + except TimeoutError: + return result(False, "timeout", f"no response within {timeout:g}s") + except Exception as exc: + return result(False, "connect", str(exc)) + + +def _select_agents( + agents: tuple[AgentDefinition, ...], + selected: set[str], +) -> list[AgentDefinition]: + if not selected: + return list(agents) + return [agent for agent in agents if agent.agent_id in selected] + + +async def run_checks(args: argparse.Namespace) -> list[AgentCheckResult]: + registry = load_agent_registry(args.config) + selected = _select_agents(registry.agents, set(args.agent)) + if not selected: + raise SystemExit("no matching agents selected") + + fallback_base_url = args.base_url or os.environ.get("AGENT_BASE_URL", "") + semaphore = asyncio.Semaphore(args.concurrency) + + async def run_one(index: int, agent: AgentDefinition) -> AgentCheckResult: + chat_id = str(args.chat_id if args.chat_id is not None else args.chat_id_base + index) + async with semaphore: + return await check_agent( + agent, + fallback_base_url=fallback_base_url, + chat_id=chat_id, + timeout=args.timeout, + message=args.message, + ) + + return await asyncio.gather(*(run_one(index, agent) for index, agent in enumerate(selected))) + + +def print_table(results: list[AgentCheckResult]) -> None: + for item in results: + status = "OK" if item.ok else "FAIL" + detail = item.response_type or item.error + print( + f"{status:4} {item.agent_id:20} {item.stage:8} " + f"{item.latency_ms:5}ms chat={item.chat_id} url={item.ws_url} {detail}" + ) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Smoke-check Matrix agent WebSocket endpoints from matrix-agents.yaml." + ) + parser.add_argument("--config", type=Path, default=Path("config/matrix-agents.yaml")) + parser.add_argument("--agent", action="append", default=[], help="Agent id to check") + parser.add_argument("--base-url", default="", help="Fallback base URL when an agent has none") + parser.add_argument("--timeout", type=float, default=10.0) + parser.add_argument("--concurrency", type=int, default=5) + parser.add_argument("--chat-id", type=int, default=None, help="Use one explicit chat id") + parser.add_argument("--chat-id-base", type=int, default=900000) + parser.add_argument("--message", default=None, help="Optional test message after STATUS") + parser.add_argument("--json", action="store_true", help="Print machine-readable JSON") + return parser.parse_args() + + +def main() -> int: + args = parse_args() + results = asyncio.run(run_checks(args)) + if args.json: + print(json.dumps([asdict(result) for result in results], ensure_ascii=False, indent=2)) + else: + print_table(results) + return 0 if all(result.ok for result in results) else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/no_status_agent.py b/tools/no_status_agent.py new file mode 100644 index 0000000..adb563a --- /dev/null +++ b/tools/no_status_agent.py @@ -0,0 +1,33 @@ +from __future__ import annotations + +import argparse +import asyncio + +from aiohttp import web + + +async def websocket_handler(request: web.Request) -> web.WebSocketResponse: + ws = web.WebSocketResponse() + await ws.prepare(request) + await asyncio.sleep(3600) + return ws + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="WebSocket stub that accepts connections but sends no STATUS." + ) + parser.add_argument("--host", default="127.0.0.1") + parser.add_argument("--port", type=int, default=8000) + return parser.parse_args() + + +def main() -> None: + args = parse_args() + app = web.Application() + app.router.add_get("/v1/agent_ws/{chat_id}/", websocket_handler) + web.run_app(app, host=args.host, port=args.port) + + +if __name__ == "__main__": + main() From e7e3912b5f381c110f53c894f73e3620be10c06e Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 00:01:25 +0300 Subject: [PATCH 50/55] docs: generalize new surface guide and clean up legacy docs --- README.md | 1 + docs/api-contract.md | 143 -------------- docs/matrix-direct-agent-prototype-ru.md | 3 + docs/matrix-prototype.md | 2 +- ...-surface-guide.md => new-surface-guide.md} | 80 ++++---- docs/surface-protocol.md | 21 ++- docs/telegram-prototype.md | 3 + docs/user-flow.md | 65 ------- docs/workflow-backup-2026-04-01.md | 174 ------------------ 9 files changed, 59 insertions(+), 433 deletions(-) delete mode 100644 docs/api-contract.md rename docs/{max-surface-guide.md => new-surface-guide.md} (79%) delete mode 100644 docs/user-flow.md delete mode 100644 docs/workflow-backup-2026-04-01.md diff --git a/README.md b/README.md index 3b8a7a6..51e92f9 100644 --- a/README.md +++ b/README.md @@ -279,3 +279,4 @@ pytest tests/adapter/matrix/ -v # только Matrix | [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Команды бота, UX, передача файлов | | [`docs/known-limitations.md`](docs/known-limitations.md) | Известные ограничения и обходные пути | | [`docs/surface-protocol.md`](docs/surface-protocol.md) | Внутренний протокол событий (для расширения) | +| [`docs/new-surface-guide.md`](docs/new-surface-guide.md) | Руководство по созданию новой поверхности (Discord, Slack и др.) | diff --git a/docs/api-contract.md b/docs/api-contract.md deleted file mode 100644 index 10fd899..0000000 --- a/docs/api-contract.md +++ /dev/null @@ -1,143 +0,0 @@ -# API Contract — Lambda Platform - -> **Статус:** ЧЕРНОВИК — проектируем сами, уточняем с Азаматом когда SDK будет готов -> **Последнее обновление:** 2026-03-29 - ---- - -## Архитектурный контекст - -Каждому пользователю выделяется **один LXC-контейнер** с workspace 10 ГБ. -Workspace содержит директории чатов: `C1/`, `C2/`, `C3/` — файлы + `history.db` в каждом. - -**Master** управляет lifecycle контейнера (запуск, заморозка, пробуждение). -Бот **не управляет lifecycle** — он передаёт `user_id` + `chat_id` + сообщение. -Master сам решает: нужно ли поднять контейнер, смонтировать нужный чат, запустить агента. - ---- - -## Base URL - -``` -https://api.lambda-platform.io/v1 -``` - -## Аутентификация - -``` -Authorization: Bearer {SERVICE_TOKEN} -``` - -Сервисный токен выдаётся команде поверхностей. Не путать с токеном пользователя. - ---- - -## Users - -### GET /users/{external_id}?platform={platform} - -Получает или создаёт пользователя. - -**Query params:** -- `platform` — `telegram` | `matrix` - -**Response 200:** -```json -{ - "user_id": "usr_abc123", - "external_id": "12345678", - "platform": "telegram", - "display_name": "Иван Иванов", - "created_at": "2025-01-15T10:30:00Z", - "is_new": false -} -``` - ---- - -## Messages - -Бот не управляет сессиями явно. Отправка сообщения — единственная операция. -Master решает: нужен ли новый контейнер, или разбудить существующий. - -### POST /users/{user_id}/chats/{chat_id}/messages - -Отправляет сообщение пользователя агенту. Master поднимает/размораживает контейнер, -монтирует нужный чат (`C1/`, `C2/`...), запускает агента. - -**Request:** -```json -{ - "text": "Привет, что ты умеешь?", - "attachments": [] -} -``` - -**Response 200:** -```json -{ - "message_id": "msg_qwe012", - "response": "Я AI-агент Lambda...", - "tokens_used": 142, - "finished": true -} -``` - ---- - -## Settings - -### GET /users/{user_id}/settings - -Настройки пользователя: скиллы, коннекторы, SOUL, безопасность, план. - -**Response 200:** -```json -{ - "skills": {"web-search": true, "browser": false}, - "connectors": {"gmail": {"connected": true, "email": "user@gmail.com"}}, - "soul": {"name": "Лямбда", "style": "friendly"}, - "safety": {"email-send": true, "file-delete": true}, - "plan": {"name": "Beta", "tokens_used": 800, "tokens_limit": 1000} -} -``` - -### POST /users/{user_id}/settings - -Применяет действие над настройками. - -**Request:** -```json -{ - "action": "toggle_skill", - "payload": {"skill": "browser", "enabled": true} -} -``` - -**Response 200:** -```json -{"ok": true} -``` - ---- - -## Error format - -```json -{ - "error": "ERROR_CODE", - "message": "Human readable description", - "details": {} -} -``` - -Коды ошибок: `USER_NOT_FOUND`, `RATE_LIMITED`, `PLATFORM_ERROR`, `CONTAINER_UNAVAILABLE` - ---- - -## Открытые вопросы к команде платфрмы (SDK) - -- [ ] Точный формат эндпоинта отправки сообщения — URL, поля -- [ ] Как передавать вложения (файлы, изображения)? Через S3 pre-signed URL или напрямую? -- [ ] Стриминговый ответ (SSE / WebSocket) или только sync? -- [ ] Формат `SettingsAction` — совпадает с нашим или другой? diff --git a/docs/matrix-direct-agent-prototype-ru.md b/docs/matrix-direct-agent-prototype-ru.md index 8f1dcee..2367dc5 100644 --- a/docs/matrix-direct-agent-prototype-ru.md +++ b/docs/matrix-direct-agent-prototype-ru.md @@ -1,5 +1,8 @@ # Matrix Direct-Agent Prototype +> **ВНИМАНИЕ: Это исторический документ.** +> Описанный здесь прототип был интегрирован в `main` и стал основой для Matrix MVP, но архитектура претерпела значительные изменения. Для актуальной информации по деплою смотрите `docs/deploy-architecture.md`, а для создания новой поверхности — `docs/max-surface-guide.md`. + Русскоязычная заметка по прототипу Matrix surface, который ходит не в `MockPlatformClient`, а напрямую в живой agent backend по WebSocket. ## Что сделали diff --git a/docs/matrix-prototype.md b/docs/matrix-prototype.md index 4d944db..d79ff83 100644 --- a/docs/matrix-prototype.md +++ b/docs/matrix-prototype.md @@ -84,7 +84,7 @@ Matrix-клиенты отправляют файлы и текст отдель ## Передача файлов ### Пользователь → Агент -Бот сохраняет файл в shared volume: `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` +Бот сохраняет файл в shared volume: `{workspace_path}/{filename}` и передаёт агенту относительный путь как `workspace_path`. ### Агент → Пользователь diff --git a/docs/max-surface-guide.md b/docs/new-surface-guide.md similarity index 79% rename from docs/max-surface-guide.md rename to docs/new-surface-guide.md index 15b98f1..d057c4e 100644 --- a/docs/max-surface-guide.md +++ b/docs/new-surface-guide.md @@ -1,6 +1,6 @@ -# Руководство по созданию новой поверхности Max +# Руководство по созданию новой поверхности -Этот документ описывает, как написать новую поверхность для Max по образцу текущей Matrix-поверхности в ветке `feat/deploy`. +Этот документ описывает, как написать новую новую поверхность (например, Discord, Slack или Custom Web) по образцу текущей Matrix-поверхности в ветке `main`. Он основан на актуальной реализации Matrix surface в репозитории и отражает текущую продакшн-логику, а не устаревший легаси. @@ -10,7 +10,7 @@ ### 1.1. Что такое поверхность -Поверхность — это тонкий адаптер между конкретной платформой (Max) и общим ядром бота. +Поверхность — это тонкий адаптер между конкретной платформой (Платформа) и общим ядром бота. В репозитории есть разделение: @@ -24,17 +24,17 @@ Поверхность должна: -- принимать нативные события от Max +- принимать нативные события от Платформа - преобразовывать их в единый внутренний контракт (`IncomingMessage`, `IncomingCommand`, `IncomingCallback`) - передавать их в `core` - получать ответы из `core` (`OutgoingMessage`, `OutgoingUI`, `OutgoingTyping`, `OutgoingNotification`) -- преобразовывать ответы обратно в нативные Max-сообщения +- преобразовывать ответы обратно в нативные нативные сообщения Поверхность не должна: - управлять жизненным циклом агентских контейнеров - хранить долгую историю бесед вне `core`/платформы -- аутентифицировать пользователей сама (если это не часть Max API) +- аутентифицировать пользователей сама (если это не часть Платформа API) --- @@ -42,10 +42,10 @@ ### 2.1. Основные каталоги -Рекомендуемая структура для Max: +Рекомендуемая структура для новой платформы: ``` -adapter/max/ +adapter// bot.py converter.py agent_registry.py @@ -56,14 +56,14 @@ adapter/max/ ### 2.2. Принцип reuse -По примеру Matrix surface, Max surface должен переиспользовать общий `core` и общий `sdk`. +По примеру Matrix surface, New surface должен переиспользовать общий `core` и общий `sdk`. Не дублируйте бизнес-логику, а реализуйте только адаптер: -- `adapter/max/converter.py` — конвертация событий Max ⇄ внутренние структуры -- `adapter/max/bot.py` — основной runtime, старт Max client, loop, отправка/прием -- `adapter/max/agent_registry.py` — загрузка `config/max-agents.yaml` -- `adapter/max/files.py` — хранение входящих/исходящих вложений +- `adapter//converter.py` — конвертация событий платформы ⇄ внутренние структуры +- `adapter//bot.py` — основной runtime, старт Платформа client, loop, отправка/прием +- `adapter//agent_registry.py` — загрузка `config/-agents.yaml` +- `adapter//files.py` — хранение входящих/исходящих вложений --- @@ -89,7 +89,7 @@ adapter/max/ - `!list`/`!remove` говорят не агенту, а surface-процессу - вложения `m.file`, `m.image`, `m.audio`, `m.video` нормализуются в `Attachment` -Для Max реализуйте аналогичную логику для native команд вашего клиента. +Для Платформа реализуйте аналогичную логику для native команд вашего клиента. --- @@ -122,11 +122,11 @@ agents: Это важно: именно на этом контракте строится разделение агентов по рабочим каталогам. -### 4.3. Рекомендуемая Max-версия +### 4.3. Рекомендуемая Версия для новой платформы -Создайте `config/max-agents.yaml` с тем же смыслом. +Создайте `config/-agents.yaml` с тем же смыслом. -- `user_agents` — маппинг Max user_id → agent_id +- `user_agents` — маппинг external user_id → agent_id - `agents` — список агентов - `workspace_path` для каждого агента должен быть абсолютным путем внутри surface-контейнера, например `/agents/0` @@ -181,15 +181,15 @@ Matrix-реализация использует `platform_chat_id` как ст - `reconcile_startup_state()` восстанавливает отсутствующие `platform_chat_id` при рестарте - `RoutedPlatformClient` перенаправляет запросы агенту по `agent_id` + `platform_chat_id` -Для Max surface тот же принцип: +Для New surface тот же принцип: - каждая внешняя беседа должна привязываться к одному внутреннему `chat_id` - этот `chat_id` используется для вызовов агента -- если в Max есть несколько комнат/топиков, каждая должна иметь свой `surface_ref` +- если в Платформа есть несколько комнат/топиков, каждая должна иметь свой `surface_ref` ### 6.2. Команды управления чатами -Matrix поддерживает следующие команды, которые нужно сохранить в Max: +Matrix поддерживает следующие команды, которые нужно сохранить в Платформа: - `!new [название]` — создать новый чат - `!chats` — список активных чатов @@ -211,7 +211,7 @@ Matrix surface поддерживает staged attachments: - surface сохраняет файл в `staged_attachments` для конкретного room_id + user_id - следующий текст отправляется агенту вместе со всеми файлами из очереди -В Max можно реализовать ту же модель: +В Платформа можно реализовать ту же модель: - `!list` показывает текущую очередь - `!remove` удаляет файл из очереди @@ -233,10 +233,10 @@ Matrix surface поддерживает staged attachments: - `AGENT_BASE_URL` — fallback URL агента - `SURFACES_WORKSPACE_DIR` — путь к shared volume внутри контейнера (по умолчанию `/workspace` в коде, но в docs рекомендуют `/agents`) -Для Max surface используйте аналогичные переменные: +Для New surface используйте аналогичные переменные: -- `MAX_PLATFORM_BACKEND=real` -- `MAX_AGENT_REGISTRY_PATH=/app/config/max-agents.yaml` +- `PLATFORM_PLATFORM_BACKEND=real` +- `PLATFORM_AGENT_REGISTRY_PATH=/app/config/-agents.yaml` - `SURFACES_WORKSPACE_DIR=/agents` - `AGENT_BASE_URL` — если хотите общий fallback @@ -248,7 +248,7 @@ Matrix surface поддерживает staged attachments: - `_load_agent_registry_from_env()` читает `MATRIX_AGENT_REGISTRY_PATH` - `_build_platform_from_env()` выбирает `RealPlatformClient` при `MATRIX_PLATFORM_BACKEND=real` -В Max surface реализуйте ту же логику, заменив префиксы на `MAX_`. +В New surface реализуйте ту же логику, заменив префиксы на `PLATFORM_`. --- @@ -264,7 +264,7 @@ Matrix surface поддерживает staged attachments: - `tests/adapter/matrix/test_reconciliation.py` - `tests/adapter/matrix/test_context_commands.py` -Для Max создайте аналогичные тесты: +Для Платформа создайте аналогичные тесты: - проверка загрузки вложений - проверка маршрутизации по `agent_id` @@ -275,11 +275,11 @@ Matrix surface поддерживает staged attachments: Для Matrix surface есть `docker-compose.prod.yml` и `docker-compose.fullstack.yml`. -Для Max surface должно быть достаточно: +Для New surface должно быть достаточно: - bot-only production deployment - shared volume `/agents` -- независимая проверка `config/max-agents.yaml` +- независимая проверка `config/-agents.yaml` - проверка, что surface запускается без локального агента ### 8.3. Проверка контрактов @@ -295,22 +295,22 @@ Matrix surface поддерживает staged attachments: ## 9. Реализация шаг за шагом -1. Скопировать `adapter/matrix/` как шаблон для `adapter/max/`. -2. Сделать `adapter/max/converter.py`: - - превратить native Max-сообщения в `IncomingMessage` +1. Скопировать `adapter/matrix/` как шаблон для `adapter//`. +2. Сделать `adapter//converter.py`: + - превратить native нативные сообщения в `IncomingMessage` - превратить команды в `IncomingCommand` - превратить yes/no-подтверждения в `IncomingCallback` -3. Сделать `adapter/max/agent_registry.py` на основе `adapter/matrix/agent_registry.py`. -4. Сделать `adapter/max/files.py` на основе `adapter/matrix/files.py`. -5. Сделать `adapter/max/bot.py`: +3. Сделать `adapter//agent_registry.py` на основе `adapter/matrix/agent_registry.py`. +4. Сделать `adapter//files.py` на основе `adapter/matrix/files.py`. +5. Сделать `adapter//bot.py`: - инстанцировать runtime - - читать env vars `MAX_*` + - читать env vars `PLATFORM_*` - загружать реестр агентов - обрабатывать входящие события - - отправлять `Outgoing*` обратно в Max + - отправлять `Outgoing*` обратно в Платформа 6. Реализовать команды управления чатами и очередь вложений. -7. Прописать `config/max-agents.yaml`. -8. Прописать `docker-compose.max.yml` или аналог, чтобы surface монтировал `/agents`. +7. Прописать `config/-agents.yaml`. +8. Прописать `docker-compose.platform.yml` или аналог, чтобы surface монтировал `/agents`. 9. Написать тесты по аналогии с `tests/adapter/matrix/`. 10. Проверить, что все env vars читаются из окружения и не зависят от устаревших Matrix-переменных. @@ -318,10 +318,10 @@ Matrix surface поддерживает staged attachments: ## 10. Важные замечания -- Текущий Matrix surface на ветке `feat/deploy` — активная реализация, а не устаревший легаси. +- Текущий Matrix surface на ветке `main` — активная реализация, а не устаревший легаси. - Документация и код согласованы: `agent_registry`, `files`, `routed_platform`, `reconciliation` работают вместе. - Обязательно явно задавайте `SURFACES_WORKSPACE_DIR=/agents` в production, если `workspace_path` в реестре указывает на `/agents/*`. -- Для Max surface сохраните ту же архитектуру: surface = thin adapter, агенты = внешние сервисы. +- Для New surface сохраните ту же архитектуру: surface = thin adapter, агенты = внешние сервисы. - Не пытайтесь в surface реализовывать логику запуска/стопа агент-контейнеров. --- diff --git a/docs/surface-protocol.md b/docs/surface-protocol.md index ca66000..f2bd7b1 100644 --- a/docs/surface-protocol.md +++ b/docs/surface-protocol.md @@ -38,9 +38,10 @@ surfaces-bot/ converter.py — matrix-nio Event → IncomingEvent, OutgoingEvent → Matrix API bot.py — точка входа, клиент - platform/ - interface.py — Protocol: PlatformClient - mock.py — MockPlatformClient + sdk/ + interface.py — Protocol: PlatformClient (контракт к SDK) + real.py — RealPlatformClient (через AgentApi) + mock.py — MockPlatformClient (для локальных тестов) ``` --- @@ -140,7 +141,7 @@ class UIButton: ``` Telegram рендерит это как InlineKeyboard. -Matrix рендерит как текст с описанием реакций или HTML-кнопки. +Matrix рендерит как текст (в MVP). ### OutgoingNotification Асинхронное уведомление — агент закончил долгую задачу. @@ -209,7 +210,7 @@ class ConfirmationRequest: ``` Telegram показывает как Inline-кнопки. -Matrix показывает как реакции 👍 / ❌. +Matrix показывает как запрос для `!yes` / `!no`. Ядро не знает как именно — только получает `IncomingCallback` с `action: "confirm"`. --- @@ -304,9 +305,9 @@ class PlatformClient(Protocol): async def update_settings(self, user_id: str, action: Any) -> None: ... ``` -Бот **не управляет lifecycle контейнеров** — это делает Master (платформа). -Бот передаёт `user_id` + `chat_id` + текст; Master сам решает нужно ли поднять контейнер, смонтировать `C1/`/`C2/`, запустить агента. +Бот **не управляет lifecycle контейнеров** агентов. Запуск/перезапуск агентов — ответственность платформы. +Бот передаёт `user_id` + `chat_id` + текст. -`MockPlatformClient` реализует этот протокол сейчас. -Реальный SDK — тоже реализует этот протокол, заменяя один файл. -Адаптеры поверхностей и ядро не меняются вообще. +`MockPlatformClient` реализует этот протокол для локальных тестов. +Реальный SDK используется через `RealPlatformClient` (`sdk/real.py`), который подключается к `AgentApi` по WebSocket. +Адаптеры поверхностей и ядро не меняются вообще, привязка идёт через `config/matrix-agents.yaml`. diff --git a/docs/telegram-prototype.md b/docs/telegram-prototype.md index c58a1e5..17f93cf 100644 --- a/docs/telegram-prototype.md +++ b/docs/telegram-prototype.md @@ -1,5 +1,8 @@ # Telegram — описание прототипа +> **ВНИМАНИЕ: Telegram-адаптер не является частью текущего MVP-деплоя.** +> Код Telegram-поверхности находится в отдельной ветке `feat/telegram-adapter`. Данный документ описывает возможности этого адаптера, но многие концепции (например, AuthFlow и MockPlatformClient) устарели по отношению к актуальной архитектуре `main`. + ## Концепция Один бот, несколько чатов через Topics в Forum-группе. diff --git a/docs/user-flow.md b/docs/user-flow.md deleted file mode 100644 index efe22f1..0000000 --- a/docs/user-flow.md +++ /dev/null @@ -1,65 +0,0 @@ -# User Flow — Lambda Bot - -> **Статус:** ШАБЛОН — заполняет @architect после исследований -> **Зависит от:** docs/research/telegram-flows.md, docs/research/competitor-ux.md - ---- - -## Основной сценарий (happy path) - -```mermaid -sequenceDiagram - actor User - participant Bot as Telegram/Matrix Bot - participant Platform as Lambda Platform (Master) - - User->>Bot: /start - Bot->>Platform: GET /users/{tg_id}?platform=telegram - Platform-->>Bot: {user_id, is_new} - - alt Новый пользователь - Bot->>User: Приветствие + инструкция - else Существующий пользователь - Bot->>User: Добро пожаловать обратно - end - - loop Диалог (бот не управляет сессиями — Master делает это автоматически) - User->>Bot: Сообщение в чат C1/C2/... - Bot->>Platform: POST /users/{user_id}/chats/{chat_id}/messages - Note over Platform: Master поднимает контейнер,
монтирует нужный чат, запускает агента - Platform-->>Bot: {message_id, response, tokens_used} - Bot->>User: Ответ агента - end -``` - ---- - -## Состояния FSM (Telegram) - -```mermaid -stateDiagram-v2 - [*] --> Unauthenticated: первый контакт - - Unauthenticated --> Idle: /start (auth confirmed) - - Idle --> WaitingResponse: сообщение пользователя - WaitingResponse --> Idle: ответ получен - WaitingResponse --> Error: ошибка платформы - - Idle --> Idle: /new (создан новый чат) - Idle --> ConfirmAction: агент запрашивает подтверждение - ConfirmAction --> Idle: подтверждено / отменено - - Error --> Idle: /start -``` - ---- - -## Открытые вопросы - -> Заполняет @researcher и @architect после исследований - -- [ ] Как выглядит онбординг новых пользователей у конкурентов? -- [ ] Нужна ли кнопка "Новая сессия" или сессия стартует автоматически? -- [ ] Что показываем пока агент думает (typing indicator)? -- [ ] Как обрабатываем timeout ответа от платформы? diff --git a/docs/workflow-backup-2026-04-01.md b/docs/workflow-backup-2026-04-01.md deleted file mode 100644 index 9b77d68..0000000 --- a/docs/workflow-backup-2026-04-01.md +++ /dev/null @@ -1,174 +0,0 @@ -# Surfaces team — Lambda Lab 3.0 - -Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda. - -## Правило №1: не быть ждуном - -Платформа (SDK от Азамата) ещё не готова. Это **не блокер**. - -- Все вызовы платформы — через `platform/interface.py` (Protocol) -- Реализация сейчас — `platform/mock.py` (MockPlatformClient) -- При подключении реального SDK — меняем только `platform/mock.py` -- Архитектурные решения принимаем сами, фиксируем в `docs/api-contract.md` - ---- - -## Архитектура - -``` -surfaces-bot/ - core/ - protocol.py — унифицированные структуры (IncomingMessage, OutgoingUI, ...) - handler.py — EventDispatcher: IncomingEvent → OutgoingEvent (общее для всех ботов) - handlers/ — обработчики по типам событий (start, message, chat, settings, callback) - store.py — StateStore Protocol + InMemoryStore + SQLiteStore - chat.py — ChatManager: метаданные чатов C1/C2/C3 - auth.py — AuthManager: AuthFlow - settings.py — SettingsManager: SettingsAction - - adapter/ - telegram/ — aiogram адаптер - converter.py — aiogram Event → IncomingEvent и обратно - bot.py — точка входа - handlers/ — aiogram роутеры - keyboards/ — инлайн-клавиатуры - states.py — FSM состояния - matrix/ — matrix-nio адаптер - converter.py — matrix-nio Event → IncomingEvent и обратно - bot.py — точка входа - handlers/ — обработчики событий - - platform/ - interface.py — Protocol: PlatformClient (контракт к SDK) - mock.py — MockPlatformClient (заглушка) - - docs/ — вся документация - tests/ — pytest тесты - .claude/agents/ — конфиги агентов -``` - -Подробно об унификации: `docs/surface-protocol.md` -Telegram функционал: `docs/telegram-prototype.md` -Matrix функционал: `docs/matrix-prototype.md` - ---- - -## Агенты - -| Агент | Когда запускать | Модель | Токены | -|-------|----------------|--------|--------| -| `@researcher` | Изучить API, найти примеры | Haiku | ~дёшево | -| `@architect` | Спроектировать решение | Sonnet | ~средне | -| `@tg-developer` | Писать код Telegram-адаптера | Sonnet | ~средне | -| `@matrix-developer` | Писать код Matrix-адаптера | Sonnet | ~средне | -| `@core-developer` | Писать core/ и platform/ | Sonnet | ~средне | -| `@reviewer` | Проверить код перед PR | Sonnet | ~средне | - -**Важно (Pro-лимиты):** не запускай больше двух Sonnet-агентов одновременно. -Haiku можно запускать параллельно сколько угодно. - ---- - -## Стратегия параллельной разработки - -Два бота разрабатываются параллельно, но через общее ядро. - -### Порядок работы - -``` -1. core/ — сначала (однократно, все ждут) - @core-developer пишет protocol.py, handler.py, session.py, auth.py, settings.py - -2. platform/ — сразу после core/ - @core-developer пишет interface.py и mock.py - -3. adapter/telegram/ и adapter/matrix/ — параллельно - @tg-developer → adapter/telegram/ - @matrix-developer → adapter/matrix/ - Не пересекаются по файлам — можно одновременно в разных терминалах. -``` - -### Что можно делать одновременно (разные терминалы) - -```bash -# Терминал 1 — Telegram адаптер -claude "Use @tg-developer to implement adapter/telegram/handlers/start.py" - -# Терминал 2 — Matrix адаптер (параллельно) -claude "Use @matrix-developer to implement adapter/matrix/handlers/start.py" -``` - -### Что нельзя делать одновременно - -- Два агента в одном файле -- @core-developer параллельно с @tg-developer или @matrix-developer - (core/ должен быть готов до адаптеров) -- Больше двух Sonnet-агентов одновременно (Pro-лимит) - ---- - -## Git worktree workflow - -Каждая фича в отдельном worktree — адаптеры не мешают друг другу: - -```bash -# Создать worktrees для параллельной работы -git worktree add .worktrees/telegram -b feat/telegram-adapter -git worktree add .worktrees/matrix -b feat/matrix-adapter - -# Работать в каждом независимо -cd .worktrees/telegram && claude "Use @tg-developer to ..." -cd .worktrees/matrix && claude "Use @matrix-developer to ..." - -# Смержить когда готово -git checkout main -git merge feat/telegram-adapter -git merge feat/matrix-adapter -``` - ---- - -## Команды запуска - -```bash -# Установить зависимости -uv sync - -# Запустить тесты -pytest tests/ -v - -# Запустить только тесты Telegram -pytest tests/adapter/telegram/ -v - -# Запустить только тесты Matrix -pytest tests/adapter/matrix/ -v - -# Запустить только тесты ядра -pytest tests/core/ -v - -# Запустить Telegram бота -python -m adapter.telegram.bot - -# Запустить Matrix бота -python -m adapter.matrix.bot -``` - ---- - -## Переменные окружения - -```bash -cp .env.example .env -``` - -Никогда не коммить `.env`. - ---- - -## Экономия токенов (Pro-лимиты) - -- Исследования → всегда `@researcher` (Haiku), не Sonnet -- Точечные правки в одном файле → напрямую без агента -- Ревью → только перед PR, не после каждого коммита -- Длинный контекст → дай агенту конкретный файл, не весь проект -- Если агент "завис" в рассуждениях → прерви, переформулируй задачу точнее From 7b2543aee742724592a03980909d676dfaf0497d Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 00:06:16 +0300 Subject: [PATCH 51/55] docs: add local fullstack e2e instructions to new surface guide --- docs/new-surface-guide.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/new-surface-guide.md b/docs/new-surface-guide.md index d057c4e..f3b72b0 100644 --- a/docs/new-surface-guide.md +++ b/docs/new-surface-guide.md @@ -282,7 +282,19 @@ Matrix surface поддерживает staged attachments: - независимая проверка `config/-agents.yaml` - проверка, что surface запускается без локального агента -### 8.3. Проверка контрактов +### 8.3. Локальное E2E тестирование (fullstack) + +Для тестирования новой поверхности вместе с одним локальным агентом используйте паттерн `docker-compose.fullstack.yml`. +В этом режиме: +- Запускается 1 контейнер вашей поверхности +- Запускается 1 контейнер `platform-agent` +- Поднимается локальный shared volume (`surfaces-agents`) +- Поверхность настроена маршрутизировать запросы на `http://platform-agent:8000` (через `AGENT_BASE_URL`) +- Пользователь общается с ботом, а бот напрямую общается с локальным агентом, разделяя с ним общую папку для файлов. + +Это самый быстрый способ проверить интеграцию новой платформы без внешнего бэкенда. + +### 8.4. Проверка контрактов Особое внимание: From 6dde5be17d74277b51fd0397b14f311710e60fe5 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 00:11:01 +0300 Subject: [PATCH 52/55] docs: simplify testing section in new surface guide --- docs/new-surface-guide.md | 41 +-------------------------------------- 1 file changed, 1 insertion(+), 40 deletions(-) diff --git a/docs/new-surface-guide.md b/docs/new-surface-guide.md index f3b72b0..7ebdc2a 100644 --- a/docs/new-surface-guide.md +++ b/docs/new-surface-guide.md @@ -252,37 +252,7 @@ Matrix surface поддерживает staged attachments: --- -## 8. Тестирование и валидация - -### 8.1. Юнит-тесты - -В ветке есть покрытие для Matrix surface: - -- `tests/adapter/matrix/test_files.py` -- `tests/adapter/matrix/test_dispatcher.py` -- `tests/adapter/matrix/test_routed_platform.py` -- `tests/adapter/matrix/test_reconciliation.py` -- `tests/adapter/matrix/test_context_commands.py` - -Для Платформа создайте аналогичные тесты: - -- проверка загрузки вложений -- проверка маршрутизации по `agent_id` -- проверка восстановления `platform_chat_id` -- проверка конвертации команд - -### 8.2. Smoke-проверка deployment - -Для Matrix surface есть `docker-compose.prod.yml` и `docker-compose.fullstack.yml`. - -Для New surface должно быть достаточно: - -- bot-only production deployment -- shared volume `/agents` -- независимая проверка `config/-agents.yaml` -- проверка, что surface запускается без локального агента - -### 8.3. Локальное E2E тестирование (fullstack) +## 8. Локальное тестирование Для тестирования новой поверхности вместе с одним локальным агентом используйте паттерн `docker-compose.fullstack.yml`. В этом режиме: @@ -294,15 +264,6 @@ Matrix surface поддерживает staged attachments: Это самый быстрый способ проверить интеграцию новой платформы без внешнего бэкенда. -### 8.4. Проверка контрактов - -Особое внимание: - -- `agent_registry` должен загружать `workspace_path` -- file flow должен поддерживать `workspace_path` в `Attachment` -- отправка файлов должна использовать `resolve_workspace_attachment_path()` -- `platform_chat_id` должен существовать до вызова агента - --- ## 9. Реализация шаг за шагом From 65445f516f7c15a0e21be2608896d463ca136503 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 00:31:20 +0300 Subject: [PATCH 53/55] docs: map codebase --- .planning/codebase/ARCHITECTURE.md | 140 ++--------------- .planning/codebase/CONCERNS.md | 239 +---------------------------- .planning/codebase/CONVENTIONS.md | 200 +----------------------- .planning/codebase/INTEGRATIONS.md | 182 ++-------------------- .planning/codebase/STACK.md | 121 ++------------- .planning/codebase/STRUCTURE.md | 226 ++------------------------- .planning/codebase/TESTING.md | 217 ++------------------------ 7 files changed, 73 insertions(+), 1252 deletions(-) diff --git a/.planning/codebase/ARCHITECTURE.md b/.planning/codebase/ARCHITECTURE.md index 0cc6c4c..05f7a7f 100644 --- a/.planning/codebase/ARCHITECTURE.md +++ b/.planning/codebase/ARCHITECTURE.md @@ -1,134 +1,14 @@ -# Architecture +# Архитектура (ARCHITECTURE.md) -**Analysis Date:** 2026-04-01 +## Паттерн "Thin Adapter" (Тонкая поверхность) -## Pattern Overview +Система разделена на три логических слоя: +1. **Транспортный слой (Adapter)**: Подключается к внешней платформе (Matrix). Занимается конвертацией нативных событий (`room.message`) во внутренние структуры (`IncomingMessage`). +2. **Ядро (Core)**: Предоставляет единый протокол (`core/protocol.py`), не зависящий от конкретной реализации (Matrix, Telegram и т.д.). +3. **Платформенный слой (SDK)**: `RealPlatformClient` инкапсулирует подключение по WebSocket к реальным агентам (AgentApi). -**Overall:** Hexagonal / Ports-and-Adapters +## Routing & Registry +Бот может обслуживать множество агентов (multi-tenant). Маршрутизация настраивается статически через `config/matrix-agents.yaml`. Каждый пользователь (`@user:server`) привязан к конкретному `agent_id`, у которого есть свой HTTP URL и свой изолированный `workspace_path` (например, `/agents/1/`). -**Key Characteristics:** -- A platform-neutral `core/` defines all business logic and unified event types -- Adapters (`adapter/telegram/`, `adapter/matrix/`) translate platform-specific events into core types and back -- The AI platform SDK is hidden behind a `PlatformClient` Protocol; the current implementation (`sdk/mock.py`) is swappable without touching core or adapters -- All state is stored through a `StateStore` Protocol, with `InMemoryStore` for tests and `SQLiteStore` for production - -## Layers - -**Protocol Layer:** -- Purpose: Defines every data structure crossing layer boundaries -- Location: `core/protocol.py` -- Contains: `IncomingMessage`, `IncomingCommand`, `IncomingCallback`, `OutgoingMessage`, `OutgoingUI`, `OutgoingNotification`, `OutgoingTyping`, `ChatContext`, `AuthFlow`, `SettingsAction`, type aliases `IncomingEvent` and `OutgoingEvent` -- Depends on: Python stdlib only -- Used by: All other layers - -**Core / Business Logic Layer:** -- Purpose: Handles all domain logic independent of any platform -- Location: `core/` -- Contains: - - `core/handler.py` — `EventDispatcher`: routes `IncomingEvent` to registered handler functions; returns `list[OutgoingEvent]` - - `core/handlers/` — one module per event category (`start`, `message`, `chat`, `settings`, `callback`) - - `core/store.py` — `StateStore` Protocol + `InMemoryStore` + `SQLiteStore` - - `core/chat.py` — `ChatManager`: creates/renames/archives chat workspaces (C1/C2/C3); persists via `StateStore` - - `core/auth.py` — `AuthManager`: tracks auth flow state (`pending` → `confirmed`); persists via `StateStore` - - `core/settings.py` — `SettingsManager`: fetches/caches user settings from SDK; invalidates on write -- Depends on: `core/protocol.py`, `sdk/interface.py` (Protocol only), `core/store.py` -- Used by: Adapters - -**SDK / Platform Layer:** -- Purpose: Wraps the external Lambda AI platform; isolated behind a Protocol -- Location: `sdk/` -- Contains: - - `sdk/interface.py` — `PlatformClient` Protocol: `get_or_create_user`, `send_message`, `stream_message`, `get_settings`, `update_settings`; also `WebhookReceiver` Protocol, Pydantic models (`User`, `MessageResponse`, `MessageChunk`, `UserSettings`, `AgentEvent`) - - `sdk/mock.py` — `MockPlatformClient`: full in-memory implementation with simulated latency; supports both sync (`send_message`) and streaming (`stream_message`, currently returns single chunk); includes webhook simulation via `simulate_agent_event()` -- Depends on: `sdk/interface.py` -- Used by: `core/` managers, adapters during bot startup - -**Adapter Layer:** -- Purpose: Translates platform-native events into `IncomingEvent` and `OutgoingEvent` back to platform-native calls -- Location: `adapter/matrix/`, adapter/telegram/ (in `.worktrees/telegram/`) -- Contains per adapter: `bot.py` (entry point + send logic), `converter.py` (native event → protocol), `handlers/` (adapter-specific handler overrides registered on top of core handlers), optional `store.py` / `room_router.py` / `reactions.py` for adapter state -- Depends on: `core/`, `sdk/`, platform SDK (aiogram or matrix-nio) -- Used by: `__main__` / `asyncio.run(main())` - -## Data Flow - -**Incoming Message (Matrix example):** - -1. `matrix-nio` fires `RoomMessageText` callback → `MatrixBot.on_room_message()` in `adapter/matrix/bot.py` -2. `resolve_chat_id()` in `adapter/matrix/room_router.py` maps `room_id` → logical `chat_id` (e.g. `C1`), persisted in `StateStore` -3. `from_room_event()` in `adapter/matrix/converter.py` converts the nio event to `IncomingMessage` or `IncomingCommand` -4. `EventDispatcher.dispatch(incoming)` in `core/handler.py` selects the handler by routing key (command name, callback action, or `"*"` for messages) -5. Handler (e.g. `core/handlers/message.py:handle_message`) calls `platform.send_message()` on `MockPlatformClient`, receives `MessageResponse` -6. Handler returns `list[OutgoingEvent]` (e.g. `[OutgoingTyping(..., False), OutgoingMessage(...)]`) -7. `MatrixBot._send_all()` iterates the list; `send_outgoing()` converts each to a `client.room_send()` / `client.room_typing()` call - -**Incoming Reaction (Matrix):** - -1. `ReactionEvent` callback → `MatrixBot.on_reaction()` -2. `from_reaction()` maps emoji key to `IncomingCallback` with `action="confirm"`, `"cancel"`, or `"toggle_skill"` -3. Dispatch → `core/handlers/callback.py` - -**Command Routing:** - -The `EventDispatcher` uses a routing key per event type: -- `IncomingCommand` → `event.command` (e.g. `"start"`, `"new"`, `"settings"`) -- `IncomingCallback` → `event.action` (e.g. `"confirm"`, `"toggle_skill"`) -- `IncomingMessage` → `"*"` (catch-all), or `event.attachments[0].type` if attachments present - -Adapters call `register_all(dispatcher)` first (core handlers), then `register_matrix_handlers(dispatcher, ...)` to override or add platform-specific variants (e.g. `!new` creates a real Matrix room via the nio client). - -**State Management:** -- All persistent state goes through `StateStore` (key-value, async interface) -- Key namespaces: `chat:{user_id}:{chat_id}`, `auth:{user_id}`, `settings:{user_id}`, `matrix_room:{room_id}`, `matrix_user:{matrix_user_id}`, `matrix_state:{room_id}`, `matrix_skills_msg:{room_id}` -- Production uses `SQLiteStore` (row-per-key, JSON-serialised values); tests use `InMemoryStore` - -## Key Abstractions - -**EventDispatcher (`core/handler.py`):** -- Purpose: Single dispatch table for all event types; decouples handler logic from transport -- Pattern: Registry (map of `event_type → {key → HandlerFn}`); wildcard `"*"` as fallback -- Handler signature: `async def handler(event, chat_mgr, auth_mgr, settings_mgr, platform) → list[OutgoingEvent]` - -**StateStore Protocol (`core/store.py`):** -- Purpose: Pluggable persistence behind a minimal `get/set/delete/keys` interface -- Implementations: `InMemoryStore` (tests/dev), `SQLiteStore` (production) -- Key pattern: `"{namespace}:{discriminator}"` - -**PlatformClient Protocol (`sdk/interface.py`):** -- Purpose: Contracts the entire surface of the Lambda AI SDK -- Current implementation: `MockPlatformClient` in `sdk/mock.py` -- Swap path: Replace `sdk/mock.py` with a real SDK client; no changes needed elsewhere - -**Converter functions (`adapter/matrix/converter.py`):** -- Purpose: One-way transformation from platform-native event to `IncomingEvent` -- Always produce canonical protocol types; adapters never pass raw library objects to core - -## Entry Points - -**Matrix Bot:** -- Location: `adapter/matrix/bot.py:main()` -- Run: `python -m adapter.matrix.bot` -- Startup sequence: load `.env` → build `AsyncClient` → `build_runtime()` → register callbacks → `client.sync_forever()` - -**Telegram Bot:** -- Location: `.worktrees/telegram/adapter/telegram/bot.py` (feature branch, not merged to main yet) -- Run: `python -m adapter.telegram.bot` - -## Error Handling - -**Strategy:** Errors propagate up to the adapter's event callback. The adapter logs and drops the event; the bot keeps running. - -**Patterns:** -- `EventDispatcher.dispatch()` returns `[]` (empty list) when no handler is found and logs a warning -- `AuthManager` and `ChatManager` raise `ValueError` for not-found entities; callers are responsible for catching -- `MockPlatformClient` raises `PlatformError` (defined in `sdk/interface.py`) on unexpected states - -## Cross-Cutting Concerns - -**Logging:** `structlog` throughout; all managers and the dispatcher use `structlog.get_logger(__name__)` -**Validation:** Pydantic models in `sdk/interface.py` for SDK responses; plain dataclasses in `core/protocol.py` for internal events -**Authentication:** `AuthManager.is_authenticated()` is checked in `handle_message` before forwarding to platform; unauthenticated users receive a prompt to run `!start` / `/start` - ---- - -*Architecture analysis: 2026-04-01* +## Файловый контракт +Файлы не передаются агенту в base64. Бот сохраняет вложение напрямую в локальную директорию (общий volume), и передает агенту только относительный путь (`workspace_path`). diff --git a/.planning/codebase/CONCERNS.md b/.planning/codebase/CONCERNS.md index 473d257..5848135 100644 --- a/.planning/codebase/CONCERNS.md +++ b/.planning/codebase/CONCERNS.md @@ -1,235 +1,6 @@ -# Codebase Concerns +# Известные проблемы (CONCERNS.md) -**Analysis Date:** 2026-04-01 - ---- - -## Tech Debt - -### Telegram adapter not merged to main - -- Issue: The entire `adapter/telegram/` directory exists only in the `feat/telegram-adapter` branch (worktree at `.worktrees/telegram/`). `main` has no Telegram adapter at all. -- Files: `.worktrees/telegram/adapter/telegram/` and remote branch `origin/feat/telegram-adapter` -- Impact: Running `python -m adapter.telegram.bot` from `main` fails with ImportError. Tests referencing `adapter/telegram/` (e.g., `tests/adapter/test_forum_db.py`) only exist in the worktree and are absent from `main`. -- Fix approach: Merge `feat/telegram-adapter` into `main` after final manual QA pass. The branch is ahead of main by 5 commits (`a1b7a14` being the most recent). - -### Divergent core/handlers between main and feat/telegram-adapter - -- Issue: `feat/telegram-adapter` removed platform-awareness from `core/handlers/chat.py` and `core/handlers/message.py` — the `_command()` and `_start_command()` helpers that format Matrix `!cmd` vs Telegram `/cmd` prompts were deleted. The branch hardcodes `/start` everywhere. -- Files: `core/handlers/chat.py`, `core/handlers/message.py` (differ between branches) -- Impact: If the Matrix adapter relies on these platform-aware helpers being in `main`'s version of core, merging `feat/telegram-adapter` will break Matrix `!start` prompt text for unauthenticated users. -- Fix approach: Before merging, decide which version of `core/handlers/` is canonical. The Matrix adapter in `main` currently passes because `main` still has the platform-aware helpers. - -### SQLiteStore uses blocking I/O in async context - -- Issue: `core/store.py` `SQLiteStore` methods are declared `async` but perform synchronous blocking `sqlite3.connect()` calls without `asyncio.to_thread` or `aiosqlite`. -- Files: `core/store.py` lines 46–73 -- Impact: Each database call blocks the asyncio event loop. Under any concurrent load (e.g., two Matrix users sending messages simultaneously) this will cause visible latency spikes and potential event loop starvation. -- Fix approach: Replace `sqlite3` calls with `aiosqlite` or wrap each call in `asyncio.to_thread()`. - -### Telegram adapter has its own separate SQLite database layer - -- Issue: `adapter/telegram/db.py` is a fully independent SQLite database (file: `lambda_bot.db`) with its own schema (`tg_users`, `chats`). Meanwhile, `core/store.py` has `SQLiteStore` with a KV schema (`lambda_matrix.db` for Matrix). The two stores are incompatible and do not share data. -- Files: `.worktrees/telegram/adapter/telegram/db.py`, `core/store.py` -- Impact: There is no unified storage layer. Chat state is split across two databases. A user's Telegram chats cannot be seen from Matrix and vice versa (even conceptually). Violates the "single core" architecture principle from CLAUDE.md. -- Fix approach: This is a fundamental design gap. Either extend `StateStore` to support the Telegram-specific data model, or accept separate stores as intentional for the prototype stage and document the constraint. - -### MockPlatformClient hardcoded throughout — no production path wired - -- Issue: Both `adapter/matrix/bot.py` and `.worktrees/telegram/adapter/telegram/bot.py` instantiate `MockPlatformClient()` directly. `PLATFORM_MODE` is defined in `.env.example` but is never read or acted upon anywhere in the codebase. -- Files: `adapter/matrix/bot.py` line 71, `sdk/mock.py`, `sdk/interface.py` -- Impact: There is no runtime switch to connect a real SDK. Switching to production requires code changes, not configuration. -- Fix approach: Add a factory function in `sdk/` that reads `PLATFORM_MODE` and returns either `MockPlatformClient` or a real `PlatformClient`. Both bot entrypoints should use this factory. - -### MatrixRuntime type annotation leaks MockPlatformClient - -- Issue: `adapter/matrix/bot.py` `MatrixRuntime.platform` is typed as `MockPlatformClient` (not `PlatformClient`). `build_event_dispatcher` and `build_runtime` signatures also use `MockPlatformClient` as the parameter type. -- Files: `adapter/matrix/bot.py` lines 46, 54, 67 -- Impact: The isolation promise ("replace only `sdk/mock.py` when real SDK arrives") is broken — the bot layer is coupled to the mock concrete type, not the Protocol. -- Fix approach: Change type annotations to `PlatformClient` from `sdk.interface`. - ---- - -## Known Bugs / Open Issues - -### Telegram forum: global commands visible inside topic context - -- Issue: Telegram shows the full bot command menu (including `/chats`, `/new`, `/settings`) even when the user is inside a forum topic. The code blocks `switch` and `new_chat` callbacks inside topics but the commands themselves still appear in the UI. -- Files: `.worktrees/telegram/adapter/telegram/handlers/forum.py`, `.worktrees/telegram/adapter/telegram/bot.py` -- Impact: Users can tap `/settings` or `/chats` inside a topic and get confusing behavior. -- Tracked: Issue `#15` — `Telegram forum topics: remaining UX and synchronization gaps` - -### Telegram forum: `/new ` inside linked topic does not rename the Telegram topic - -- Issue: Running `/new ` inside a forum topic that is already linked to a chat renames the internal chat record but does not call `edit_forum_topic` to rename the actual Telegram topic. -- Files: `.worktrees/telegram/adapter/telegram/handlers/forum.py` -- Impact: Topic name in Telegram goes out of sync with internal chat name. -- Tracked: Issue `#15` - -### Matrix: `handle_invite` hardcodes `chat_id = "C1"` for all new rooms - -- Issue: `adapter/matrix/handlers/auth.py` `handle_invite()` always assigns `chat_id = "C1"` regardless of how many rooms the user already has. If a user invites the bot into a second room before using `!new`, both rooms get `C1`. -- Files: `adapter/matrix/handlers/auth.py` line 26 -- Impact: Two rooms mapped to the same `chat_id` causes routing collisions. -- Fix approach: Call `next_chat_id(store, user_id)` here instead of hardcoding `"C1"`. - -### Matrix: `remove_reaction` uses non-standard `undo` field - -- Issue: `adapter/matrix/reactions.py` `remove_reaction()` sends a `"undo": True` field in the reaction event body. This is not part of the Matrix spec for reaction redaction. The correct approach is to redact the original reaction event via `client.room_redact()`. -- Files: `adapter/matrix/reactions.py` lines 56–68 -- Impact: Reaction "undo" will silently fail on compliant homeservers. - -### Matrix: E2EE not supported (blocked by `python-olm`) - -- Issue: `matrix-nio` E2EE requires `python-olm`, which fails to build on macOS/ARM. No encrypted DM support. -- Files: `adapter/matrix/bot.py` -- Impact: The bot cannot operate in encrypted rooms. Users who have DM encryption enforced cannot use the Matrix bot. -- Status: Documented as a known infrastructure constraint in `docs/reports/2026-04-01-surfaces-progress-report.md`. Needs a separate infrastructure task. - ---- - -## Security Considerations - -### SQLite database files not in .gitignore - -- Risk: `lambda_bot.db` and `lambda_matrix.db` are present in the working tree (shown in `git status`) but not listed in `.gitignore`. These files may contain user data including chat content and display names. -- Files: `lambda_bot.db`, `lambda_matrix.db`, `.gitignore` -- Current mitigation: Files are currently untracked (not yet staged) but nothing prevents them from being accidentally committed. -- Recommendation: Add `*.db` or specific filenames to `.gitignore` immediately. - -### Auth flow is auto-confirmed in mock — no real validation exists - -- Issue: `core/auth.py` `confirm()` automatically sets `state = "confirmed"` and generates a fake `platform_user_id`. There is no real verification step, no code exchange, no token validation. -- Files: `core/auth.py` lines 39–48 -- Impact: The auth layer is decorative for the prototype. Any user who sends `!start` or `/start` is immediately authenticated. If the real SDK auth requires a different flow (e.g., OAuth, code), the current `AuthManager` interface may not match. -- Current mitigation: Acceptable for mock stage. Must be re-evaluated before production use. - -### Matrix room metadata stored without access control - -- Issue: `adapter/matrix/store.py` stores room metadata keyed by `room_id`. Any call that can supply an arbitrary `room_id` can read or overwrite another user's room metadata. -- Files: `adapter/matrix/store.py`, `adapter/matrix/room_router.py` -- Impact: In the current single-process bot this is not exploitable. If the store is ever shared across processes or users, room metadata can be poisoned. - ---- - -## Fragile Areas - -### `core/chat.py` scan-by-suffix fallback is O(N) and collision-prone - -- Issue: `ChatManager.get()` when called without `user_id` scans all `chat:*` keys and matches by suffix (e.g., `":C1"`). If two users both have a chat named `C1` (which is always the case), this returns the first one found, non-deterministically. -- Files: `core/chat.py` lines 76–82 -- Impact: Functions like `rename` and `archive` that call `chat_mgr.get(chat_id)` without `user_id` will operate on the wrong user's chat in a multi-user scenario. -- Fix approach: Audit all callers and always pass `user_id`. The scan-by-suffix fallback should be removed or explicitly guarded. - -### `adapter/matrix/handlers/chat.py` chat_id counter races under concurrency - -- Issue: `make_handle_new_chat` calls `chat_mgr.list_active()` and uses `len(chats) + 1` to compute a new `chat_id`. This is not atomic. Two concurrent `!new` commands from the same user can produce the same `chat_id`. -- Files: `adapter/matrix/handlers/chat.py` line 17 -- Impact: Duplicate `chat_id` values (`C2`, `C2`) for the same user, leading to state corruption. -- Fix approach: Use `next_chat_id()` from `adapter/matrix/store.py` which increments an atomic counter in the store. The `next_chat_id()` function already exists but is not used here. - -### `conftest.py` contains a fragile stdlib `platform` module workaround - -- Issue: `conftest.py` patches `sys.modules` to remove the Python stdlib `platform` module so local `platform/` (which no longer exists — renamed to `sdk/`) doesn't shadow it. The comment still refers to `platform/` but the directory was renamed to `sdk/` in commit `41660fe`. -- Files: `conftest.py` lines 1–13 -- Impact: The workaround is now a no-op (there is no `platform/` package to shadow) but adds confusion. The comment is incorrect. If someone creates a `platform/` directory again, unexpected behavior can return. -- Fix approach: Remove the `sys.modules` patching entirely since `sdk/` does not conflict with stdlib. Update the comment. - -### Forum onboarding `chat_shared` constructs a fake `Chat` object - -- Issue: `adapter/telegram/handlers/forum.py` handles `chat_shared` by constructing `Chat(id=..., type="supergroup", is_forum=True)` and passing it to `_complete_group_link()`. The `is_forum=True` is hardcoded — the real value from Telegram is not verified. This means the check `if getattr(forwarded_chat, "is_forum", None) is False` in the forwarding fallback path is bypassed entirely. -- Files: `.worktrees/telegram/adapter/telegram/handlers/forum.py` lines 162–168 -- Impact: A user could link a regular supergroup (without Topics enabled) via `chat_shared`, which would succeed in linking but fail when the bot tries to create forum topics. - ---- - -## Gaps Between CLAUDE.md and Actual Code - -### CLAUDE.md says `platform/` — code uses `sdk/` - -- CLAUDE.md architecture diagram shows `platform/interface.py` and `platform/mock.py` -- Actual code uses `sdk/interface.py` and `sdk/mock.py` (renamed in commit `41660fe`) -- Files: `CLAUDE.md` (project instructions), `sdk/interface.py`, `sdk/mock.py` -- Also: Agent config files at `.claude/agents/core-developer.md` still reference `platform/` throughout -- Impact: New contributors reading CLAUDE.md will look for a `platform/` directory that does not exist. - -### CLAUDE.md lists `core/handlers/` sub-handlers that partially do not exist - -- CLAUDE.md lists handler modules but the actual `core/handlers/` only has: `start.py`, `message.py`, `chat.py`, `settings.py`, `callback.py` -- No `voice.py` handler exists; voice is handled as a fallback inside `core/handlers/message.py` (returns stub response) -- No `payment.py` handler exists; `PaymentRequired` dataclass is defined in `core/protocol.py` but never dispatched -- Files: `core/protocol.py` (PaymentRequired defined), `core/handlers/` (no payment or voice handlers) - -### CLAUDE.md workflow describes `@reviewer` agent but agent file references old patterns - -- `.claude/agents/core-developer.md` still says "Твоя зона — `core/` и `platform/`" -- The old Haiku/Sonnet researcher-developer workflow is captured in `docs/workflow-backup-2026-04-01.md`, but `.claude/agents/` configs were not updated to match - -### `tests/adapter/test_forum_db.py` is untracked on main - -- This test file exists in the working tree (visible in `git status`) but is not committed to `main`. It tests `adapter/telegram/db.py` which also does not exist on `main`. -- Files: `tests/adapter/test_forum_db.py` -- Impact: Running `pytest tests/` from main currently includes this test, which imports `adapter.telegram.db`. This import succeeds only because the test auto-reloads the module from an untracked file. This is fragile — if the file is deleted, tests silently pass with fewer tests counted. - ---- - -## Missing Critical Features - -### No streaming response support in adapters - -- Both adapters use `platform.send_message()` (sync) not `platform.stream_message()` (streaming) -- `sdk/interface.py` defines `stream_message` returning `AsyncIterator[MessageChunk]` -- No adapter sends a typing indicator before the response arrives and then streams chunks -- Impact: User experience with slow AI responses will show nothing until the full response is ready -- Files: `core/handlers/message.py` line 28, `sdk/interface.py` lines 83–88 - -### No webhook/push notification handling - -- `sdk/interface.py` defines `WebhookReceiver` Protocol with `on_agent_event()` -- `sdk/mock.py` has `register_webhook_receiver()` and `simulate_agent_event()` -- Neither bot entrypoint registers a `WebhookReceiver` -- Impact: Push notifications from the platform (task completions, background jobs) cannot reach the user -- Files: `sdk/interface.py` lines 95–97, `adapter/matrix/bot.py`, no registration present - -### Telegram adapter uses InMemoryStore for core state - -- `.worktrees/telegram/adapter/telegram/bot.py` calls `InMemoryStore()` for the `EventDispatcher`'s state -- All `core/` state (auth, chat metadata in the KV layer) is lost on bot restart -- `adapter/telegram/db.py` SQLite is used only for Telegram-specific data -- Impact: On restart, authenticated users are logged out; core chat context is wiped -- Files: `.worktrees/telegram/adapter/telegram/bot.py` line 46 - -### No multi-user isolation in Matrix store - -- `adapter/matrix/store.py` keys are global (`matrix_room:ROOMID`, `matrix_user:USERID`) -- There is no namespace or tenant isolation -- Impact: At scale, any key collision would corrupt state. For a single-user prototype this is acceptable, but it is an architectural constraint to document before expanding scope. - ---- - -## Test Coverage Gaps - -### No tests for `adapter/telegram/` in main test suite - -- `tests/adapter/` on main only contains `matrix/` tests and the untracked `test_forum_db.py` -- All Telegram adapter tests live in the worktree at `.worktrees/telegram/tests/` -- Files: `tests/adapter/` (missing `telegram/` subdirectory on main) -- Risk: Merging `feat/telegram-adapter` without also merging its tests leaves Telegram untested on main -- Priority: High - -### No tests for `core/handlers/callback.py` confirm/cancel real behavior - -- `core/handlers/callback.py` `handle_confirm` and `handle_cancel` return stub text with `action_id` -- No test verifies that a real confirmation flow (dispatch → confirm → side effect) works end to end -- Files: `core/handlers/callback.py`, `tests/core/test_dispatcher.py` -- Priority: Medium - -### No tests for `adapter/matrix/handlers/auth.py` multi-room invite scenario - -- The hardcoded `C1` bug (see Known Bugs section) is not caught by any test -- Files: `adapter/matrix/handlers/auth.py`, `tests/adapter/matrix/test_dispatcher.py` -- Priority: Medium - ---- - -*Concerns audit: 2026-04-01* +- **Отсутствие E2E шифрования в Matrix**: На данный момент бот не поддерживает зашифрованные комнаты, так как библиотека `matrix-nio` требует нативной сборки `python-olm`, что усложняет кросс-платформенный деплой. +- **Потеря стейта агентов**: Так как текущий `platform-agent` часто работает с `MemorySaver`, его стейт теряется при перезапусках. Это проблема внешнего агента, но она напрямую влияет на UX поверхности. +- **Общий том (Shared Volume)**: Контракт обязывает бота и агента запускаться на одном физическом хосте (или иметь распределенный сетевой диск), что может стать бутылочным горлышком при сильном масштабировании. +- **Hardcoded роутинг**: `matrix-agents.yaml` требует ручного редактирования и перезапуска бота при добавлении новых агентов. Желательно вынести этот процесс в динамическую БД или API. diff --git a/.planning/codebase/CONVENTIONS.md b/.planning/codebase/CONVENTIONS.md index 04c7f6a..36a4ed5 100644 --- a/.planning/codebase/CONVENTIONS.md +++ b/.planning/codebase/CONVENTIONS.md @@ -1,195 +1,7 @@ -# Coding Conventions +# Конвенции (CONVENTIONS.md) -**Analysis Date:** 2026-04-01 - -## Linting and Formatting - -**Tool:** ruff (configured in `pyproject.toml`) - -**Settings:** -- Line length: 100 characters -- Target: Python 3.11 -- Active rule sets: `E` (pycodestyle errors), `F` (pyflakes), `I` (isort), `UP` (pyupgrade), `B` (bugbear) - -**Type checking:** mypy (available as dev dependency; not enforced in CI at this time) - -Run linting: -```bash -ruff check . -ruff format . -``` - -## File Naming - -- Module files: `snake_case.py` (e.g., `room_router.py`, `test_dispatcher.py`) -- Each module starts with a comment declaring its path: `# core/handler.py` -- Test files: `test_.py` (e.g., `test_store.py`, `test_converter.py`) -- No index/barrel files except `__init__.py` for package registration - -## Class Naming - -- `PascalCase` for all classes (e.g., `EventDispatcher`, `MockPlatformClient`, `MatrixBot`) -- Protocol/interface classes named after the capability: `StateStore`, `PlatformClient`, `WebhookReceiver` -- Manager classes suffixed with `Manager`: `ChatManager`, `AuthManager`, `SettingsManager` -- Dataclasses follow the same `PascalCase` rule: `IncomingMessage`, `OutgoingUI`, `MatrixRuntime` - -## Function and Method Naming - -- `snake_case` for all functions and methods -- Private helpers prefixed with single underscore: `_to_dict`, `_from_dict`, `_routing_key`, `_latency` -- Handler functions named `handle_`: `handle_start`, `handle_message`, `handle_new_chat` -- Builder functions named `build_`: `build_runtime`, `build_event_dispatcher`, `build_skills_text` -- Converter functions named `from_`: `from_room_event`, `from_command`, `from_reaction` -- Predicate functions named `is_`: `is_authenticated`, `is_new` - -## Variable Naming - -- `snake_case` for all variables and parameters -- Internal state attributes prefixed with `_`: `self._store`, `self._platform`, `self._handlers` -- Store key prefixes are module-level constants in `UPPER_SNAKE_CASE`: - ```python - ROOM_META_PREFIX = "matrix_room:" - USER_META_PREFIX = "matrix_user:" - ``` -- Constants for reaction strings are module-level: `CONFIRM_REACTION = "👍"`, `PLATFORM = "matrix"` - -## Type Annotations - -All files use `from __future__ import annotations` at the top for deferred evaluation. - -**Annotation style:** -- Use built-in generics (`list[str]`, `dict[str, Any]`) — not `List`, `Dict` from `typing` -- Union types written with `|`: `str | None`, `IncomingCallback | None` -- Type aliases at module level: `IncomingEvent = IncomingMessage | IncomingCommand | IncomingCallback` -- Callable types use `typing.Callable` and `typing.Awaitable`: - ```python - HandlerFn = Callable[..., Awaitable[list[OutgoingEvent]]] - ``` -- Handler functions use loose `list` return type without generics (consistent across `core/handlers/`) -- Protocol classes use `...` as body for abstract methods: - ```python - async def get(self, key: str) -> dict | None: ... - ``` - -**Pydantic vs dataclasses:** -- `core/protocol.py` — plain `@dataclass` with `field(default_factory=...)` for mutable defaults -- `sdk/interface.py` — Pydantic `BaseModel` for all SDK-facing models (`User`, `MessageResponse`, `UserSettings`) -- Choose `@dataclass` for internal protocol structs, `BaseModel` for SDK boundary models - -## Import Organization - -Order (enforced by ruff `I` rules): -1. `from __future__ import annotations` -2. Standard library imports (grouped) -3. Third-party imports (grouped) -4. Local imports from project packages (grouped) - -Example from `adapter/matrix/bot.py`: -```python -from __future__ import annotations - -import asyncio -import os -from dataclasses import dataclass -from pathlib import Path - -import structlog -from nio import AsyncClient, ... -from dotenv import load_dotenv - -from adapter.matrix.converter import from_reaction, from_room_event -from core.auth import AuthManager -from core.protocol import OutgoingEvent, ... -from sdk.mock import MockPlatformClient -``` - -No relative imports; all imports use absolute package paths from the project root. - -## Async Patterns - -All I/O methods are `async def`. There are no sync wrappers around async code. - -**Handler signature pattern** (used uniformly across `core/handlers/`): -```python -async def handle_(event: IncomingEvent, auth_mgr, platform, chat_mgr, settings_mgr) -> list: -``` -Note: manager parameters are untyped in handler signatures (accepted as `**kwargs` at call site in `EventDispatcher.dispatch`). - -**Awaiting store calls:** -```python -stored = await self._store.get(f"auth:{user_id}") -await self._store.set(f"auth:{user_id}", _to_dict(flow)) -``` - -**SQLiteStore uses sync sqlite3** inside `async def` methods — blocking I/O is not off-loaded to a thread executor. This is a known limitation (see CONCERNS.md). - -**Mock latency simulation:** -```python -await self._latency(200, 600) # min_ms, max_ms -``` - -## Logging - -**Library:** `structlog` - -**Pattern:** -```python -import structlog -logger = structlog.get_logger(__name__) - -logger.info("Chat created", chat_id=chat_id, user_id=user_id) -logger.warning("No handler registered", event_type=event_type.__name__, key=key) -``` - -- Always pass structured keyword arguments — never use f-strings in log calls -- Logger created at module level with `structlog.get_logger(__name__)` - -## Error Handling - -- Raise `ValueError` for invalid domain state (e.g., chat not found in `ChatManager.rename`) -- `sdk/interface.py` defines `PlatformError(Exception)` with a `code` field for SDK-level errors -- Handler functions never raise — they return `[]` or a fallback `OutgoingMessage` -- No `try/except` blocks in core handlers; errors from the platform are expected to propagate - -## Comments - -- Module-level comment declaring file path at top: `# core/handler.py` -- Docstrings for classes with non-obvious behavior: - ```python - class MockPlatformClient: - """ - Заглушка SDK платформы Lambda. - ... - """ - ``` -- Inline comments for non-obvious blocks: - ```python - # Scan by chat_id suffix when user_id unknown (slower) - ``` -- Comments in Russian are normal and acceptable throughout the codebase - -## Serialization Pattern - -Dataclasses are serialized/deserialized via private module-level functions, not class methods: - -```python -def _to_dict(ctx: ChatContext) -> dict: - return { "chat_id": ctx.chat_id, ... } - -def _from_dict(d: dict) -> ChatContext: - return ChatContext(chat_id=d["chat_id"], ...) -``` - -This pattern is used in `core/auth.py` and `core/chat.py`. Follow this pattern for any new manager that persists to `StateStore`. - -## Module Design - -- No barrel `__init__.py` exports except `core/handlers/__init__.py` which exposes `register_all` -- Manager classes take `(platform, store)` as constructor args; `platform` is often stored as `object` or not stored at all if unused -- `@dataclass` is preferred for plain data containers, not NamedTuple or TypedDict -- Store key namespacing follows `::` pattern: - `"chat:u1:C1"`, `"auth:u1"`, `"matrix_room:!r:m.org"` - ---- - -*Convention analysis: 2026-04-01* +- **Асинхронность**: Весь код бота асинхронный (`asyncio`). Вызовы SDK и Matrix-клиента выполняются через `await`. Блокирующие вызовы (если они есть) должны выноситься в тредпул. +- **Обработка ошибок**: Бот не должен падать из-за ошибок отдельного агента. Ошибки SDK (например, `PlatformError`) отлавливаются в боте и возвращаются пользователю в виде системных сообщений или уведомлений. +- **Стейтлесс-подход**: Поверхность хранит минимальный стейт (только локальный SQLite для связки `room_id` <-> `platform_chat_id`). Вся история сообщений и память лежат на стороне агентов. +- **Переменные окружения**: Бот полностью конфигурируется через `.env` (префиксы `MATRIX_` и `SURFACES_`). +- **Добавление новой поверхности**: Новая поверхность должна быть самостоятельной папкой в `adapter/`, реализовывать `converter.py`, и переиспользовать `sdk/real.py` и `core/protocol.py`. diff --git a/.planning/codebase/INTEGRATIONS.md b/.planning/codebase/INTEGRATIONS.md index 3cdae98..cd771d1 100644 --- a/.planning/codebase/INTEGRATIONS.md +++ b/.planning/codebase/INTEGRATIONS.md @@ -1,173 +1,15 @@ -# External Integrations +# Интеграции (INTEGRATIONS.md) -**Analysis Date:** 2026-04-01 +## Platform Agent API +- **Тип**: WebSocket (через `AgentApi` SDK) +- **Назначение**: Связь между Matrix-адаптером и внешней LLM-платформой. +- **Контракт**: Surface выступает "тупым" клиентом. Он отправляет `platform_chat_id` и `user_id` вместе с сообщениями. Платформа/Агент отвечает текстом и вложениями. Контейнерами агентов бот не управляет. -## Bot Platform APIs +## Matrix Homeserver +- **Тип**: HTTP/HTTPS API (via `matrix-nio`) +- **Назначение**: Пользовательский интерфейс и транспорт сообщений для бота. +- **Ограничения**: Поддерживается только нешифрованное (unencrypted) взаимодействие. -**Telegram Bot API:** -- Purpose: Primary messaging surface for user ↔ Lambda agent interaction -- Client library: `aiogram` 3.26.0 (async, wraps Telegram Bot API v7+) -- Authentication: Bot token via `TELEGRAM_BOT_TOKEN` -- Entry point: `adapter/telegram/bot.py` (planned; aiogram worktree branch `feat/telegram-adapter`) -- Transport: Long-polling or webhook (aiogram supports both; mode not yet locked in) -- Bot API docs: https://core.telegram.org/bots/api - -**Matrix Client-Server API:** -- Purpose: Secondary messaging surface (Matrix/Element clients) -- Client library: `matrix-nio` 0.25.2 (async) -- Authentication: password login or pre-existing access token (`MATRIX_ACCESS_TOKEN`) -- Login flow in `adapter/matrix/bot.py` `main()`: - - If `MATRIX_ACCESS_TOKEN` is set → assigned directly to `client.access_token` - - Else if `MATRIX_PASSWORD` is set → `client.login(password=..., device_name="surfaces-bot")` -- Sync method: `client.sync_forever(timeout=30000)` (30-second long-poll) -- E2EE store: nio file-based store at path from `MATRIX_STORE_PATH` (default: `"matrix_store"`) -- Matrix C-S API docs: https://spec.matrix.org/latest/client-server-api/ - -### Matrix Room Model - -Rooms are mapped to Lambda chat slots (C1, C2, C3…) via `adapter/matrix/room_router.py`: -- First message in a room → assigns next chat ID (C1, C2, …) and persists mapping to store -- Room metadata stored under key `matrix_room:` in `StateStore` -- User metadata (next chat index) stored under `matrix_user:` - -### Matrix Event Types Handled - -| nio Event Class | Handler | Action | -|--------------------|-----------------------------|-------------------------------| -| `RoomMessageText` | `MatrixBot.on_room_message` | Dispatch to `EventDispatcher` | -| `ReactionEvent` | `MatrixBot.on_reaction` | Button confirmation / skill toggle | -| `InviteMemberEvent`| `MatrixBot.on_member` | Accept room invite | -| `RoomMemberEvent` | `MatrixBot.on_member` | Membership change handling | - -## Lambda Platform (Internal SDK) - -**Purpose:** AI agent backend — processes user messages, manages user accounts, returns responses - -**Interface:** `sdk/interface.py` — `PlatformClient` Protocol - -**Current Implementation:** `sdk/mock.py` — `MockPlatformClient` -- Simulates network latency (10–80 ms default, 200–600 ms for message calls) -- In-process in-memory state (users, messages, settings dicts) -- Supports webhook simulation via `simulate_agent_event()` - -**Production Integration (future):** -- URL: `LAMBDA_PLATFORM_URL` (default: `http://localhost:8000`) -- Auth: `LAMBDA_SERVICE_TOKEN` (bearer token) -- Mode switch: `PLATFORM_MODE=mock` vs `PLATFORM_MODE=production` -- Swap path: replace `sdk/mock.py` only; no changes to `core/` or `adapter/` - -**Platform API Methods (from `sdk/interface.py`):** - -```python -async def get_or_create_user(external_id, platform, display_name) -> User -async def send_message(user_id, chat_id, text, attachments) -> MessageResponse -async def stream_message(user_id, chat_id, text, attachments) -> AsyncIterator[MessageChunk] -async def get_settings(user_id) -> UserSettings -async def update_settings(user_id, action) -> None -``` - -**Webhook / Push (outbound from platform → bot):** -- Interface: `WebhookReceiver` Protocol (`sdk/interface.py`) -- Registration: `MockPlatformClient.register_webhook_receiver(receiver)` -- Event types: `task_done`, `task_error`, `task_progress` (modelled in `AgentEvent`) -- Production implementation not yet wired; mock supports `simulate_agent_event()` for testing - -## Data Storage - -**Databases:** - -*SQLite (primary persistence):* -- Client: stdlib `sqlite3` (synchronous, called from async code without `asyncio.to_thread`) -- Schema: single key-value table: `kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)` -- JSON serialization for values (`json.dumps` / `json.loads`) -- Matrix bot DB path: `MATRIX_DB_PATH` (default: `"lambda_matrix.db"`) -- Telegram bot DB path: implicit `"lambda_bot.db"` (file present in repo root — development artifact) -- Implementation: `core/store.py` `SQLiteStore` - -*In-Memory (testing / development):* -- `InMemoryStore` — plain Python dict, no persistence across restarts -- `MockPlatformClient` internal state — also in-memory dicts - -**File Storage:** -- Matrix nio E2EE store: local filesystem directory at `MATRIX_STORE_PATH` (default: `"matrix_store/"`) -- No object storage (S3/GCS/etc.) currently; mock client has `attachment_mode` flag (`"url"` | `"binary"` | `"s3"`) reserved for future real SDK - -**Caching:** -- None — no Redis or external cache layer - -## Authentication & Identity - -**Telegram Auth:** -- Bot token → passed to aiogram dispatcher at startup -- User identity: Telegram user ID mapped to platform `external_id` - -**Matrix Auth:** -- Password or access token (see above) -- User identity: Matrix user ID (e.g. `@user:matrix.org`) mapped to platform `external_id` - -**Lambda Platform User Identity:** -- `get_or_create_user(external_id, platform)` → returns `User` with internal `user_id` -- External IDs are platform-prefixed in mock: `"{platform}:{external_id}"` - -## Monitoring & Observability - -**Logging:** -- `structlog` 25.5.0 — structured logging (key=value pairs) -- Logger instantiation: `structlog.get_logger(__name__)` in each module -- Log calls use keyword arguments: `logger.info("event_name", key=value, ...)` -- No log shipping / aggregation configured (local stdout only) - -**Error Tracking:** -- None — no Sentry, Datadog, or similar integration - -**Metrics:** -- None — `MockPlatformClient.get_stats()` returns basic in-memory counters (not exported) - -## CI/CD & Deployment - -**Hosting:** -- Not specified — no Dockerfile, docker-compose, or cloud config files present - -**CI Pipeline:** -- None detected — no `.github/workflows/`, `.gitlab-ci.yml`, etc. - -## Environment Configuration - -**Required variables (from `.env.example`):** - -| Variable | Required | Default | Purpose | -|-----------------------|----------|--------------------|--------------------------------------| -| `TELEGRAM_BOT_TOKEN` | Yes* | — | Telegram Bot API token | -| `MATRIX_HOMESERVER` | Yes* | — | Matrix homeserver URL (e.g. `https://matrix.org`) | -| `MATRIX_USER_ID` | Yes* | — | Bot's Matrix user ID | -| `MATRIX_PASSWORD` | Cond. | — | Login password (if no access token) | -| `MATRIX_ACCESS_TOKEN` | Cond. | — | Pre-issued access token (preferred) | -| `MATRIX_DEVICE_ID` | No | `""` | Matrix device ID | -| `MATRIX_DB_PATH` | No | `"lambda_matrix.db"` | SQLite DB file path (Matrix bot) | -| `MATRIX_STORE_PATH` | No | `"matrix_store"` | nio E2EE store directory | -| `LAMBDA_PLATFORM_URL` | No** | `http://localhost:8000` | Lambda platform base URL | -| `LAMBDA_SERVICE_TOKEN`| No** | — | Service auth token for Lambda API | -| `PLATFORM_MODE` | No | `"mock"` | `"mock"` or `"production"` | - -\* Required for the respective bot to function. -\*\* Only required when `PLATFORM_MODE=production`. - -**Secrets location:** -- `.env` file (gitignored) -- Never committed — `.env.example` provides template -- Loaded via `python-dotenv` at module import in each `bot.py` entry point - -## Webhooks & Callbacks - -**Incoming (platform → bot):** -- `WebhookReceiver.on_agent_event(event: AgentEvent)` — receives async task completion notifications -- Not yet wired to an HTTP endpoint; `MockPlatformClient.simulate_agent_event()` used for testing - -**Outgoing (bot → external):** -- Telegram: all via `aiogram` polling or webhook (no direct outbound HTTP beyond Telegram API) -- Matrix: all via `matrix-nio` `AsyncClient.room_send()`, `room_typing()`, etc. -- Platform: via `PlatformClient` send/stream methods - ---- - -*Integration audit: 2026-04-01* +## Файловая система (Shared Volume) +- **Тип**: Docker Shared Volume (`/agents/`) +- **Назначение**: Прямая передача файлов между поверхностью и агентами в обход сети. Поверхность пишет файлы в поддиректорию конкретного агента, агент их читает, и наоборот. diff --git a/.planning/codebase/STACK.md b/.planning/codebase/STACK.md index 708a4bf..b40772d 100644 --- a/.planning/codebase/STACK.md +++ b/.planning/codebase/STACK.md @@ -1,113 +1,14 @@ -# Technology Stack +# Технологический стек (STACK.md) -**Analysis Date:** 2026-04-01 +## Язык и Runtime +- **Python**: 3.11-slim (используется в Docker-образах) +- **Пакетный менеджер**: `uv` (используется для быстрой и строгой установки зависимостей, frozen lockfiles). -## Languages +## Ключевые библиотеки +- **matrix-nio**: Асинхронный клиент для Matrix (события, синхронизация, отправка). +- **pydantic**: Для валидации структур данных (события из AgentApi). +- **structlog**: Структурированное логирование (json/console). -**Primary:** -- Python 3.11+ — all application code (enforced via `pyproject.toml` `requires-python = ">=3.11"`) - -**Type Annotations:** -- Full `from __future__ import annotations` usage throughout -- `typing.Protocol` used for dependency inversion (`core/store.py`, `sdk/interface.py`) - -## Runtime - -**Environment:** -- CPython — runtime (development host currently runs 3.14.3) -- Minimum: Python 3.11 (uses `match`-compatible union syntax, `Self`, `X | Y` type hints) - -**Package Manager:** -- `uv` 0.9.30 (Homebrew) -- Lockfile: `uv.lock` present and committed -- Install: `uv sync` - -## Frameworks - -**Telegram Bot:** -- `aiogram` 3.26.0 — async Telegram Bot API framework - - Used in `adapter/telegram/` (planned; directory not yet present in main branch) - - Brings in `aiohttp` 3.13.3 as its HTTP transport - -**Matrix Bot:** -- `matrix-nio` 0.25.2 — async Matrix Client-Server API client - - Used in `adapter/matrix/bot.py` - - Key classes: `AsyncClient`, `AsyncClientConfig`, `RoomMessageText`, `ReactionEvent`, `InviteMemberEvent`, `RoomMemberEvent`, `MatrixRoom` - - Long-polling via `client.sync_forever(timeout=30000)` - -**Data Validation:** -- `pydantic` 2.12.5 — data models in `sdk/interface.py` - - `User`, `Attachment`, `MessageResponse`, `MessageChunk`, `UserSettings`, `AgentEvent`, `PlatformError` - - Core protocol structs (`core/protocol.py`) use plain `dataclasses` instead - -**Build/Dev:** -- `setuptools` ≥68 + `setuptools-scm` + `wheel` — build backend (`pyproject.toml`) -- `ruff` 0.15.8 — linting and import sorting (`line-length = 100`, `target-version = "py311"`, rules: E, F, I, UP, B) -- `mypy` 1.19.1 — static type checking - -## Key Dependencies - -**Critical:** -- `aiogram>=3.4,<4` (resolved: 3.26.0) — Telegram adapter; pin avoids breaking v4 API -- `matrix-nio>=0.21` (resolved: 0.25.2) — Matrix adapter; async-only client -- `pydantic>=2.5` (resolved: 2.12.5) — SDK interface models; v2 required (v1 incompatible) - -**Infrastructure:** -- `structlog` 25.5.0 — structured logging throughout; used via `structlog.get_logger(__name__)` -- `python-dotenv` 1.2.2 — loads `.env` at bot startup (`load_dotenv(Path(...) / ".env")`) -- `httpx` 0.28.1 — available for HTTP calls (future SDK integration, not yet used in core logic) - -**Async I/O:** -- `aiohttp` 3.13.3 — transitive via aiogram; provides HTTP session to Telegram Bot API -- `asyncio` — stdlib; used directly in `sdk/mock.py` (`asyncio.sleep` for latency simulation) and all bot entry points (`asyncio.run(main())`) - -## Testing - -**Runner:** -- `pytest` 9.0.2 -- `pytest-asyncio` 1.3.0 — `asyncio_mode = "auto"` (set in `pyproject.toml`) -- `pytest-cov` 7.1.0 — coverage reporting - -**Configuration:** -- `pyproject.toml` `[tool.pytest.ini_options]`: `testpaths = ["tests"]`, `pythonpath = ["."]` -- `conftest.py` at project root - -## Internal Module Structure - -**Core (no external deps except stdlib + pydantic via sdk):** -- `core/protocol.py` — `dataclasses`-based unified event types -- `core/store.py` — `StateStore` Protocol + `InMemoryStore` (dict) + `SQLiteStore` (stdlib `sqlite3`) -- `core/handler.py` — `EventDispatcher` -- `core/auth.py`, `core/chat.py`, `core/settings.py` — domain managers - -**SDK Layer:** -- `sdk/interface.py` — `PlatformClient` Protocol (pydantic models) -- `sdk/mock.py` — `MockPlatformClient` in-process stub; simulates latency via `asyncio.sleep` - -**Adapters:** -- `adapter/matrix/` — matrix-nio integration (active) -- `adapter/telegram/` — aiogram integration (referenced in deps, worktree branch exists) - -## Configuration - -**Environment:** -- Loaded from `.env` via `python-dotenv` at startup -- See `INTEGRATIONS.md` for full variable list - -**Build:** -- `pyproject.toml` — single source of truth for deps, build, lint, test config - -## Platform Requirements - -**Development:** -- Python ≥3.11 -- `uv` for dependency management - -**Production:** -- Any environment with Python ≥3.11 -- Matrix bot: requires writable filesystem path for `matrix_store/` (nio E2EE store) and SQLite DB -- Telegram bot: stateless beyond env vars (or optionally SQLite for persistence) - ---- - -*Stack analysis: 2026-04-01* +## Инфраструктура +- **Docker / Docker Compose**: Используется для локального (fullstack) и продакшн развертывания. +- **SQLite**: Легковесная локальная база данных для хранения маппингов пользователей/комнат (`adapter/matrix/store.py`). diff --git a/.planning/codebase/STRUCTURE.md b/.planning/codebase/STRUCTURE.md index 08896a5..9ea8a18 100644 --- a/.planning/codebase/STRUCTURE.md +++ b/.planning/codebase/STRUCTURE.md @@ -1,210 +1,18 @@ -# Codebase Structure +# Структура (STRUCTURE.md) -**Analysis Date:** 2026-04-01 - -## Directory Layout - -``` -surfaces-bot/ -├── adapter/ -│ ├── __init__.py -│ └── matrix/ # matrix-nio adapter (merged to main) -│ ├── __init__.py -│ ├── bot.py # Entry point, MatrixBot class, send_outgoing() -│ ├── converter.py # nio Event → IncomingEvent -│ ├── reactions.py # Emoji constants, skills text builder -│ ├── room_router.py # room_id → chat_id resolution -│ ├── store.py # Matrix-specific StateStore helpers (room meta, user meta) -│ └── handlers/ -│ ├── __init__.py # register_matrix_handlers() -│ ├── auth.py # handle_invite (invite member event) -│ ├── chat.py # Chat creation (creates real Matrix rooms) -│ ├── confirm.py # Confirmation flow callbacks -│ └── settings.py # Settings sub-commands and toggle_skill -├── core/ -│ ├── auth.py # AuthManager: start_flow, confirm, is_authenticated -│ ├── chat.py # ChatManager: get_or_create, list_active, rename, archive -│ ├── handler.py # EventDispatcher: register, dispatch, _routing_key -│ ├── protocol.py # All shared dataclasses and type aliases -│ ├── settings.py # SettingsManager: get (cached), apply (invalidates cache) -│ ├── store.py # StateStore Protocol, InMemoryStore, SQLiteStore -│ └── handlers/ -│ ├── __init__.py # register_all() — binds all core handlers to dispatcher -│ ├── callback.py # handle_confirm, handle_cancel, handle_toggle_skill -│ ├── chat.py # handle_new_chat, handle_rename, handle_archive, handle_list_chats -│ ├── message.py # handle_message — auth guard + platform.send_message -│ ├── settings.py # handle_settings — displays settings menu -│ └── start.py # handle_start — get_or_create_user + welcome message -├── sdk/ -│ ├── __init__.py -│ ├── interface.py # PlatformClient Protocol, WebhookReceiver Protocol, Pydantic models -│ └── mock.py # MockPlatformClient — full in-memory implementation -├── tests/ -│ ├── __init__.py -│ ├── conftest.py # (root conftest — sys.path fix for local sdk/ shadowing stdlib) -│ ├── adapter/ -│ │ ├── __init__.py -│ │ ├── matrix/ -│ │ │ ├── __init__.py -│ │ │ ├── test_converter.py -│ │ │ ├── test_dispatcher.py -│ │ │ ├── test_reactions.py -│ │ │ └── test_store.py -│ │ └── test_forum_db.py # untracked — forum DB exploration -│ ├── core/ -│ │ ├── test_auth.py -│ │ ├── test_chat.py -│ │ ├── test_dispatcher.py -│ │ ├── test_integration.py -│ │ ├── test_protocol.py -│ │ ├── test_settings.py -│ │ ├── test_store.py -│ │ └── test_voice_slot.py -│ └── platform/ -│ └── test_mock.py -├── docs/ # All human documentation -├── .planning/ # GSD planning artefacts -│ └── codebase/ # Codebase map documents (this directory) -├── .claude/ -│ └── agents/ # Agent configuration files -├── .worktrees/ -│ └── telegram/ # Telegram adapter on feat/telegram-adapter branch -│ └── ... # Mirrors main layout; merged separately -├── conftest.py # Root pytest conftest: sys.path hack for local sdk/ -├── pyproject.toml # Project metadata, dependencies, ruff + pytest config -├── uv.lock # Lockfile (uv) -├── lambda_matrix.db # SQLite DB written by Matrix bot (gitignored) -└── .env.example # Environment variable template -``` - -## Directory Purposes - -**`core/`:** -- Purpose: Platform-neutral business logic. Never imports from `adapter/`. -- Key files: `protocol.py` (all shared types), `handler.py` (dispatcher), `store.py` (persistence interface) -- Add new domain logic here; keep it free of aiogram/matrix-nio imports - -**`core/handlers/`:** -- Purpose: One async function per command/callback/message type. Each returns `list[OutgoingEvent]`. -- Registration: `register_all()` in `core/handlers/__init__.py` binds them to the dispatcher -- Adapters can override any key by calling `dispatcher.register(event_type, key, fn)` after `register_all()` - -**`sdk/`:** -- Purpose: Contract (`interface.py`) and mock (`mock.py`) for the Lambda AI platform SDK -- Note: The directory is named `sdk/` in actual code (not `platform/` as CLAUDE.md describes); `handler.py` imports from `sdk.interface` -- When real SDK arrives: replace `sdk/mock.py` only; `sdk/interface.py` must not change unless the contract changes - -**`adapter/matrix/`:** -- Purpose: Everything matrix-nio-specific. Translates between nio and core protocol. -- `bot.py` owns `MatrixBot`, `build_runtime()`, `send_outgoing()`, and `main()` -- `store.py` provides key-namespaced helpers on top of `StateStore` (not a separate store implementation) -- `room_router.py` maintains the `room_id → chat_id` mapping persisted in `StateStore` - -**`adapter/telegram/`:** -- Purpose: aiogram 3.x adapter. Lives in `.worktrees/telegram/` on `feat/telegram-adapter` branch. -- Uses aiogram FSM states (`states.py`) and inline keyboards (`keyboards/`) -- Not yet merged to `main` - -**`tests/`:** -- Purpose: pytest test suite mirroring the source tree -- `tests/core/` — unit tests for each core module -- `tests/adapter/matrix/` — Matrix adapter tests (converter, dispatcher, reactions, store) -- `tests/platform/` — MockPlatformClient tests - -**`docs/`:** -- Purpose: Human-readable design documents; not consumed by code -- Key docs: `docs/surface-protocol.md` (unification rationale), `docs/api-contract.md` (SDK contract), `docs/telegram-prototype.md`, `docs/matrix-prototype.md` - -## Key File Locations - -**Entry Points:** -- `adapter/matrix/bot.py` — Matrix bot `main()`, run via `python -m adapter.matrix.bot` -- `.worktrees/telegram/adapter/telegram/bot.py` — Telegram bot entry (feature branch) - -**Shared Protocol:** -- `core/protocol.py` — single source of truth for all inter-layer data types - -**SDK Contract:** -- `sdk/interface.py` — `PlatformClient` Protocol; defines the API surface for the real SDK -- `sdk/mock.py` — `MockPlatformClient`; current runtime implementation - -**Dispatcher Registration:** -- `core/handlers/__init__.py` — `register_all()` for platform-agnostic handlers -- `adapter/matrix/handlers/__init__.py` — `register_matrix_handlers()` for Matrix overrides - -**Persistence:** -- `core/store.py` — `StateStore` Protocol, `InMemoryStore`, `SQLiteStore` -- `adapter/matrix/store.py` — Matrix-specific store helper functions (not a store implementation) - -**Configuration:** -- `pyproject.toml` — dependencies, pytest config (`asyncio_mode = "auto"`, `pythonpath = ["."]`), ruff config -- `conftest.py` — `sys.path` insert so local `sdk/` shadows stdlib `platform` module - -## Naming Conventions - -**Files:** -- Modules: `snake_case.py` -- Entry points: `bot.py` per adapter -- Converter: `converter.py` per adapter -- Handlers directory: `handlers/` per layer - -**Classes:** -- Managers: `{Domain}Manager` (e.g. `ChatManager`, `AuthManager`, `SettingsManager`) -- Bot runtime: `{Platform}Bot` (e.g. `MatrixBot`) -- Protocol types: PascalCase dataclasses (e.g. `IncomingMessage`, `OutgoingUI`) -- SDK types: PascalCase Pydantic models (e.g. `MessageResponse`, `UserSettings`) - -**Handler functions:** -- `handle_{command}` for command handlers (e.g. `handle_start`, `handle_new_chat`) -- `make_handle_{command}` for factory functions that close over adapter state (e.g. `make_handle_new_chat(client, store)`) - -**State keys:** -- `"{namespace}:{discriminator}"` — always use the prefix constants defined in `adapter/matrix/store.py` - -## Where to Add New Code - -**New core command handler:** -1. Add `async def handle_{cmd}(event, chat_mgr, auth_mgr, settings_mgr, platform) -> list` in `core/handlers/{category}.py` -2. Register it in `core/handlers/__init__.py:register_all()` with `dispatcher.register(IncomingCommand, "{cmd}", handle_{cmd})` -3. Write tests in `tests/core/test_dispatcher.py` or a dedicated `tests/core/test_{category}.py` - -**New Matrix-specific handler (needs nio client or matrix store):** -1. Add handler in `adapter/matrix/handlers/{category}.py` -2. Register in `adapter/matrix/handlers/__init__.py:register_matrix_handlers()` — this overrides the core handler for that key - -**New protocol type:** -- Add dataclass to `core/protocol.py`; update `IncomingEvent` or `OutgoingEvent` union aliases if it crosses layer boundaries -- Update `EventDispatcher._routing_key()` if it requires a new dispatch strategy - -**New StateStore key namespace:** -- Add prefix constant and helper functions in `adapter/matrix/store.py` (for Matrix-specific state) or directly in the relevant manager (for core state) - -**New test:** -- Unit tests for core logic: `tests/core/test_{module}.py` -- Adapter tests: `tests/adapter/matrix/test_{module}.py` -- Use `InMemoryStore` as the store; use `MockPlatformClient` as the platform client - -## Special Directories - -**`.worktrees/telegram/`:** -- Purpose: Git worktree for `feat/telegram-adapter` branch; full copy of the repo root -- Generated: Yes (via `git worktree add`) -- Committed: No (worktrees are local) - -**`.planning/`:** -- Purpose: GSD planning artefacts — phase plans and codebase maps -- Generated: Yes (by `/gsd:` commands) -- Committed: Yes (tracked with the repo) - -**`.claude/agents/`:** -- Purpose: Agent role configuration files for the multi-agent workflow -- Committed: Yes - -**`src/`:** -- Purpose: Contains only `surfaces_bot.egg-info/` (setuptools build artefact); no source code -- Generated: Yes -- Committed: No - ---- - -*Structure analysis: 2026-04-01* +- `core/`: + - `protocol.py` — Унифицированные структуры данных (сообщения, файлы, UI). +- `adapter/matrix/`: + - `bot.py` — Главный event-loop Matrix. + - `converter.py` — Конвертация событий Matrix-nio ⇄ `core/protocol.py`. + - `agent_registry.py` — Парсинг `matrix-agents.yaml`. + - `files.py` — Работа с вложениями и shared volume. + - `store.py` — SQLite база для маппинга чатов Matrix и `platform_chat_id`. + - `routed_platform.py` — Динамический роутинг вызовов к нужным агентам на лету. +- `sdk/`: + - `interface.py` — Интерфейс PlatformClient. + - `real.py` — Имплементация WebSocket клиента (`AgentApi`). + - `mock.py` — Мок-клиент для E2E тестов без платформы. +- `config/`: Конфиги маршрутизации (YAML). +- `docs/`: Актуальная документация по развертыванию и архитектуре. +- `docker-compose*.yml`: Продакшн и локальные манифесты для сборки. diff --git a/.planning/codebase/TESTING.md b/.planning/codebase/TESTING.md index f685abc..07311dc 100644 --- a/.planning/codebase/TESTING.md +++ b/.planning/codebase/TESTING.md @@ -1,210 +1,17 @@ -# Testing Patterns +# Тестирование (TESTING.md) -**Analysis Date:** 2026-04-01 +## Unit-тесты +Расположены в `tests/`. Покрытие сфокусировано на логике Matrix адаптера (пока он является основной поверхностью): +- Файловый контракт (`test_files.py`) +- Диспетчер и конвертация (`test_dispatcher.py`) +- Взаимодействие с PlatformClient (`test_routed_platform.py`) +- Работа с контекстными командами бота (`test_context_commands.py`) -## Test Framework +## E2E тестирование +Локально тестируется через запуск контейнеров из `docker-compose.fullstack.yml`, который поднимает один инстанс бота и один локальный `platform-agent`. Это позволяет имитировать полную цепочку взаимодействия (Matrix -> Бот -> Агент) с общим каталогом для файлов. -**Runner:** pytest 8.x -**Config:** `pyproject.toml` `[tool.pytest.ini_options]` - -```toml -[tool.pytest.ini_options] -asyncio_mode = "auto" -testpaths = ["tests"] -pythonpath = ["."] -``` - -**Async support:** pytest-asyncio with `asyncio_mode = "auto"` — all `async def` test functions run automatically without decorators. - -**Coverage:** pytest-cov (available but no minimum threshold configured) - -**Run commands:** +## Запуск тестов ```bash -pytest tests/ -v # all tests -pytest tests/core/ -v # core layer only -pytest tests/adapter/telegram/ -v # telegram adapter only -pytest tests/adapter/matrix/ -v # matrix adapter only -pytest tests/ --cov=. --cov-report=term # with coverage report +# Запуск юнит-тестов (только для Matrix адаптера) +pytest tests/adapter/matrix/ -v ``` - -## Test Directory Structure - -``` -tests/ -├── __init__.py -├── core/ -│ ├── test_auth.py — AuthManager unit tests -│ ├── test_chat.py — ChatManager unit tests -│ ├── test_dispatcher.py — EventDispatcher routing tests -│ ├── test_integration.py — full flow smoke tests (dispatcher + managers + mock) -│ ├── test_protocol.py — dataclass defaults and construction -│ ├── test_settings.py — SettingsManager unit tests -│ ├── test_store.py — InMemoryStore + SQLiteStore tests -│ └── test_voice_slot.py — handle_message() handler unit tests -├── adapter/ -│ ├── __init__.py -│ ├── test_forum_db.py — Telegram SQLite DB helpers (untracked, new) -│ └── matrix/ -│ ├── __init__.py -│ ├── test_converter.py — matrix-nio event → IncomingEvent converter -│ ├── test_dispatcher.py — full Matrix bot integration (build_runtime) -│ ├── test_reactions.py — reaction text builders and emoji mapping -│ └── test_store.py — Matrix store helper functions -└── platform/ - └── test_mock.py — MockPlatformClient behavior -``` - -Tests mirror the source tree. New tests for `adapter/telegram/` go in `tests/adapter/telegram/` (directory exists in `.worktrees/telegram` branch, not yet merged to main). - -## conftest.py - -`conftest.py` at project root (`/Users/a/MAI/sem2/lambda/surfaces-bot/conftest.py`) handles a sys.path conflict: the project has a local `platform/` (now `sdk/`) package that shadows Python's stdlib `platform` module. It inserts the project root at `sys.path[0]` and removes the cached stdlib `platform` module. - -No shared fixtures are defined in `conftest.py`. All fixtures are local to test files. - -## Test Structure - -**Fixture pattern — local to each test file:** -```python -@pytest.fixture -def mgr(): - return AuthManager(MockPlatformClient(), InMemoryStore()) - -@pytest.fixture -def store() -> InMemoryStore: - return InMemoryStore() -``` - -**Async tests require no decorator** (asyncio_mode = "auto"): -```python -async def test_not_authenticated_initially(mgr): - assert await mgr.is_authenticated("u1") is False -``` - -**Sync tests** are used for pure-function tests (protocol dataclass construction, reaction text builders): -```python -def test_incoming_message_defaults(): - msg = IncomingMessage(user_id="u1", platform="telegram", chat_id="C1", text="hi") - assert msg.attachments == [] -``` - -**Integration fixture pattern** — builds full runtime in-process: -```python -@pytest.fixture -def dispatcher(): - platform = MockPlatformClient() - store = InMemoryStore() - d = EventDispatcher( - platform=platform, - chat_mgr=ChatManager(platform, store), - auth_mgr=AuthManager(platform, store), - settings_mgr=SettingsManager(platform, store), - ) - register_all(d) - return d -``` - -## Mocking Strategy - -**Primary mock: `MockPlatformClient`** from `sdk/mock.py` - -All tests use `MockPlatformClient()` directly — it is the real mock for the SDK layer. No unittest.mock patching of `MockPlatformClient` is needed. - -**`unittest.mock.AsyncMock`** is used only when testing integration with external clients (matrix-nio `AsyncClient`): -```python -from unittest.mock import AsyncMock - -client = SimpleNamespace( - room_create=AsyncMock(return_value=SimpleNamespace(room_id="!r2:example")) -) -``` - -**`types.SimpleNamespace`** is used to fabricate matrix-nio event objects without importing the full nio library: -```python -def text_event(body: str, sender: str = "@a:m.org", event_id: str = "$e1"): - return SimpleNamespace( - sender=sender, body=body, event_id=event_id, msgtype="m.text", replyto_event_id=None - ) -``` -This is the pattern for all matrix converter tests — define factory functions at module level that return `SimpleNamespace` objects. - -**`tmp_path` pytest fixture** is used for SQLiteStore tests to get a throwaway database file: -```python -async def test_sqlite_set_and_get(tmp_path): - store = SQLiteStore(str(tmp_path / "test.db")) -``` - -**`monkeypatch.setenv`** is used in `tests/adapter/test_forum_db.py` to inject `DB_PATH` env var and reload the module with a fresh database: -```python -@pytest.fixture(autouse=True) -def fresh_db(tmp_path, monkeypatch): - db_file = str(tmp_path / "test.db") - monkeypatch.setenv("DB_PATH", db_file) - import importlib - import adapter.telegram.db as db_mod - importlib.reload(db_mod) - db_mod.init_db() - return db_mod -``` - -**What NOT to mock:** -- `InMemoryStore` — use it directly; it's a real in-memory implementation -- `MockPlatformClient` — use it directly; patching it defeats the purpose -- Core manager classes (`AuthManager`, `ChatManager`, `SettingsManager`) — always instantiate real ones - -## Test Data Patterns - -**User IDs:** short strings like `"u1"`, `"u2"`, `"tg_123"`, `"@alice:m.org"` - -**Chat IDs:** `"C1"`, `"C2"`, `"C3"` — matches the workspace slot naming - -**Platform strings:** literal `"telegram"` or `"matrix"` - -**Room IDs:** `"!r:m.org"`, `"!dm:example.org"` — valid Matrix room ID format - -No shared factories or fixtures files. Test data is constructed inline or via simple factory functions local to the test module. - -## What Is Tested - -| Area | Status | -|------|--------| -| `core/protocol.py` — dataclass defaults | Covered (`test_protocol.py`) | -| `core/store.py` — InMemoryStore + SQLiteStore | Covered (`test_store.py`) | -| `core/auth.py` — AuthManager | Covered (`test_auth.py`) | -| `core/chat.py` — ChatManager | Covered (`test_chat.py`) | -| `core/settings.py` — SettingsManager | Covered (`test_settings.py`) | -| `core/handler.py` — EventDispatcher routing | Covered (`test_dispatcher.py`) | -| `core/handlers/message.py` — handle_message | Covered (`test_voice_slot.py`) | -| Full dispatcher + all core handlers integration | Covered (`test_integration.py`) | -| `sdk/mock.py` — MockPlatformClient | Covered (`test_mock.py`) | -| `adapter/matrix/converter.py` — event parsing | Covered (`test_converter.py`) | -| `adapter/matrix/store.py` — store helpers | Covered (`test_store.py`) | -| `adapter/matrix/reactions.py` — text builders | Covered (`test_reactions.py`) | -| `adapter/matrix/bot.py` — MatrixBot + build_runtime | Covered (`test_dispatcher.py`) | -| `adapter/telegram/db.py` — SQLite helpers | Covered (`test_forum_db.py`, untracked) | - -## Coverage Gaps - -**Telegram adapter handlers** — `adapter/telegram/handlers/` (`auth.py`, `chat.py`, `confirm.py`, `forum.py`, `settings.py`) have no tests in `main`. Tests exist only in `.worktrees/telegram` branch (not yet merged). - -**Telegram converter** — `adapter/telegram/converter.py` has no tests in `main`. - -**`core/handlers/callback.py` and `core/handlers/settings.py`** — tested indirectly through integration tests but lack dedicated unit tests. - -**`adapter/matrix/room_router.py`** — `resolve_chat_id` has no direct unit tests; exercised only through `MatrixBot.on_room_message` integration path. - -**`adapter/matrix/handlers/`** — individual handler files (`auth.py`, `chat.py`, `confirm.py`, `settings.py`) are tested only via `test_dispatcher.py` integration; no isolated unit tests. - -**`sdk/mock.py` streaming** — `stream_message` is not tested; only `send_message` is covered. - -**Error paths** — `ChatManager.rename` raises `ValueError` when chat not found; no test exercises this path. Same for `ChatManager.archive`. - -## Naming Conventions - -- Test functions: `test_` — descriptive, no abbreviations -- Fixture names match the object they create: `mgr`, `store`, `dispatcher`, `deps` -- Factory functions in converter tests: `text_event()`, `file_event()`, `image_event()`, `reaction_event()` - ---- - -*Testing analysis: 2026-04-01* From 9fc0b72ab1f14f6fb5a294ef7d74f6262c1f3ec9 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 23:42:05 +0300 Subject: [PATCH 54/55] docs: clean up GSD planning state and remove outdated legacy phases --- .planning/PROJECT.md | 59 ++- .planning/ROADMAP.md | 109 +----- .planning/STATE.md | 120 +----- .../.continue-here.md | 63 ---- .../.gitkeep | 0 .../01.1-01-PLAN.md | 157 -------- .../01.1-02-PLAN.md | 167 --------- .../01.1-03-PLAN.md | 149 -------- .../01.1-CONTEXT.md | 121 ------ .../01.1-RESEARCH.md | 350 ------------------ .../01.1-VALIDATION.md | 80 ---- .../phases/02-prototype/.continue-here.md | 72 ---- 12 files changed, 61 insertions(+), 1386 deletions(-) delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.gitkeep delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-01-PLAN.md delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-02-PLAN.md delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-PLAN.md delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md delete mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-VALIDATION.md delete mode 100644 .planning/phases/02-prototype/.continue-here.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 9c859f8..d90b47e 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -2,56 +2,44 @@ ## What This Is -Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda. Каждый бот — тонкий адаптер поверх общего ядра (`core/`), изолирующего бизнес-логику от транспорта. Платформа подключается через `sdk/interface.py` Protocol; сейчас используется `MockPlatformClient`. +Surfaces (поверхности) — это тонкие адаптеры-клиенты, соединяющие мессенджеры с агентами платформы Lambda. +Текущая и главная реализация — **Matrix MVP**. Бот работает как stateless-прослойка: преобразует события Matrix во внутренний протокол `core/` и маршрутизирует их на внешние контейнеры агентов (через `AgentApi` по WebSocket). ## Core Value -Пользователь может вести диалог с Lambda-агентом через любой из поддерживаемых мессенджеров без изменения ядра системы. +Пользователь может бесшовно взаимодействовать с изолированными AI-агентами через нативные интерфейсы мессенджеров (с поддержкой пересылки файлов и работы в комнатах), в то время как сама платформа агентов не зависит от транспорта. ## Requirements ### Validated -- ✓ core/ — унифицированный протокол событий, EventDispatcher, StateStore, ChatManager, AuthManager, SettingsManager — existing -- ✓ adapter/telegram/ — forum-first адаптер (Threaded Mode), `/start`, `/new`, `/archive`, `/rename`, `/settings`, стриминг ответов — existing, QA passed -- ✓ adapter/matrix/ — Space+rooms адаптер, invite flow, `!new`, `!archive`, `!rename`, `!settings`, room-per-chat — existing -- ✓ sdk/mock.py — MockPlatformClient: `stream_message`, `get_or_create_user`, `get_settings`, `update_settings` — existing +- ✓ `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). -### Active +### Out of Scope / Deferred -- [ ] Matrix QA — ручное тестирование Matrix адаптера, фиксация багов -- [ ] SDK integration — заменить MockPlatformClient реальным Lambda SDK (когда платформа готова) -- [ ] Production hardening — конфиг для деплоя, логирование, мониторинг - -### Out of Scope - -- E2EE для Matrix (python-olm не собирается на macOS/ARM) — инфраструктурная задача, отдельный трек -- Supergroup forum mode для Telegram — заменён Threaded Mode как основным режимом -- Telegram DM-first режим — заменён forum-first (Threaded Mode) +- E2EE для Matrix (отложено из-за сложностей сборки `python-olm` на кросс-платформенных средах). +- Интеграция с Master-сервисом платформы (временно используется прямое соединение с `platform-agent` через AgentApi). +- Telegram-адаптер (вынесен в легаси ветку `feat/telegram-adapter`, MVP фокусируется на Matrix). ## Context -- Python 3.11+, aiogram 3.4+, matrix-nio 0.21+, SQLite, pytest-asyncio -- Threaded Mode — Bot API 9.3, Mac клиент имеет известные баги (новые топики не сразу видны в сайдбаре) -- Lambda platform SDK ещё не готов, всё работает через MockPlatformClient -- Архитектура: Hexagonal / Ports-and-Adapters; `core/` не зависит от транспорта - -## Constraints - -- **Tech stack**: aiogram 3.x для Telegram, matrix-nio для Matrix — не менять без обсуждения -- **Platform**: SDK подключается только через `sdk/interface.py` Protocol — core/ и adapters не трогаются при смене реализации -- **Telegram**: Threaded Mode — единственный поддерживаемый режим; `closeForumTopic`/`deleteForumTopic` не работают в personal chat forums -- **E2EE**: python-olm не собирается на текущей среде — Matrix работает только без шифрования +- Стек: Python 3.11+, `matrix-nio`, `uv`, `pydantic`. +- Бот хранит только локальную привязку (`room_id` <-> `platform_chat_id`) в SQLite. Вся долговременная память и история диалогов хранятся на стороне агента. +- Жизненный цикл контейнеров агентов управляется платформой, а не ботом. ## Key Decisions | Decision | Rationale | Outcome | |----------|-----------|---------| -| Forum-first (Threaded Mode) для Telegram | Bot API 9.3 позволяет личный чат как форум — чище, без суперпруппы | ✓ Good | -| (user_id, thread_id) как PK в chats | Изоляция контекстов по топику | ✓ Good | -| MockPlatformClient через sdk/interface.py | Не ждать SDK, разрабатывать независимо | ✓ Good | -| Space+rooms для Matrix | Room-based UX и явные чаты важнее DM-first упрощений | ✓ Good | -| Отказ от E2EE в Matrix | python-olm не собирается на macOS/ARM | — Pending | +| Space+rooms для Matrix | Room-based UX и явные чаты (по одному на тред) удобнее, чем DM-каша | ✓ Good | +| Прямая интеграция AgentApi | Master API не был готов, прямое WebSocket соединение позволяет передавать стейт и файлы | ✓ Good | +| Shared Volume для файлов | Избавляет от необходимости гонять base64 по сети, быстрый прямой доступ к файлам | ✓ Good | +| Stateless бот | Бот легко перезапускать и масштабировать, память изолирована в агентах | ✓ Good | ## Evolution @@ -61,10 +49,5 @@ Telegram и Matrix боты для взаимодействия пользова 3. New requirements emerged? → Add to Active 4. Decisions to log? → Add to Key Decisions -**After each milestone:** -1. Full review of all sections -2. Core Value check — still the right priority? -3. Update Context with current state - --- -*Last updated: 2026-04-02 after initialization* +*Last updated: 2026-05-03 after codebase consolidation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 4e8799b..ffd6801 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1,101 +1,32 @@ # Roadmap — v1.0 -## Milestone: v1.0 — Production-ready surfaces - -### Phase 1: Matrix QA & Polish - -**Goal:** Переработать Matrix адаптер с DM-first на Space+rooms, убрать реакции в пользу !yes/!no, довести до уровня "приемлемо работает" как Telegram. - -**Depends on:** Telegram QA complete - -**Plans:** 6 plans - -Plans: -- [x] 01-01-PLAN.md — Space+rooms infrastructure (store helpers, handle_invite rewrite, room_router) -- [x] 01-02-PLAN.md — Chat command handlers (!new, !archive, !rename) Space-aware -- [x] 01-03-PLAN.md — Reaction removal + !yes/!no confirmation + settings dashboard -- [x] 01-04-PLAN.md — Test suite (fix 4 broken + 12 new MAT-01..MAT-12) -- [x] 01-05-PLAN.md — Gap closure for Matrix `!yes` / `!no` pending-confirm scope -- [x] 01-06-PLAN.md — Remaining Phase 01 gap closure work (completed 2026-04-03) +## Milestone: v1.0 — Production-ready Matrix MVP +### Phase 01: Matrix QA & Polish +**Goal:** Переработать Matrix адаптер с DM-first на Space+rooms, убрать реакции в пользу `!yes`/`!no`. +**Status:** Completed **Deliverables:** - Space+rooms architecture for Matrix adapter -- !yes/!no text-based confirmation (no reactions) -- Read-only !settings dashboard -- 96+ tests green - ---- - -### Phase 01.1: Matrix restart reconciliation and dev reset workflow (INSERTED) - -**Goal:** Сделать Matrix-адаптер пригодным для повторяемого локального рестарта и ручного QA: бот восстанавливает минимальный local state из существующих Space/rooms и даёт явный dev reset workflow вместо ручного ritual reset. -**Requirements**: none explicitly mapped -**Depends on:** Phase 1 -**Plans:** 3 plans - -Plans: -- [ ] 01.1-01-PLAN.md — Non-destructive Matrix reconciliation module and tests -- [ ] 01.1-02-PLAN.md — Wire startup/bootstrap recovery into the Matrix runtime -- [ ] 01.1-03-PLAN.md — Dev reset CLI and updated Matrix restart runbook - -### Phase 2: SDK Integration - -**Goal:** Заменить MockPlatformClient реальным Lambda SDK — бот начинает работать с настоящим AI-агентом. - -**Depends on:** Phase 1, Lambda platform SDK готов +- !yes/!no text-based confirmation +- Test suite green +### Phase 04: Matrix MVP: Agent Integration +**Goal:** Подключить реального агента через `AgentApi`, добавить команды управления контекстом (`!clear`). +**Status:** Completed **Deliverables:** -- `sdk/real.py` — реализация PlatformClient через реальный SDK -- `bot.py` для обоих адаптеров переключается на реальный клиент через env var -- `stream_message` работает с реальным стримингом -- Интеграционные тесты с реальным SDK (или staging) - -### Phase 4: Matrix MVP: shared agent context and context management commands - -**Goal:** Привести Matrix-бот к рабочему состоянию для MVP-деплоя: заменить AgentSessionClient на AgentApi, добавить !save/!load/!reset/!context команды управления контекстом агента, упаковать в Docker. -**Requirements**: Replace AgentSessionClient with AgentApi; Wire AgentApi lifecycle; Implement !save, !load, !reset, !context commands; Dockerfile + docker-compose -**Depends on:** Phase 1 (Matrix adapter complete) -**Plans:** 3 plans - -Plans: -- [x] 04-01-PLAN.md — Replace AgentSessionClient with AgentApi; update sdk/real.py, bot.py, broken tests -- [x] 04-02-PLAN.md — !save, !load, !reset, !context handlers; PrototypeStateStore extensions; numeric interception -- [x] 04-03-PLAN.md — Dockerfile + docker-compose.yml + .env.example update - ---- +- `sdk/real.py` — реализация `PlatformClient` через реальный SDK (`AgentApi`). +- Поддержка WebSocket стриминга. +- Команды управления контекстом. +- Обертка в Docker. ### Phase 05: MVP Deployment - -**Goal:** Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru без потери Space+rooms UX: закрепить per-room `platform_chat_id`, реальный `!clear`, reconciliation, file transfer через shared volume и разделение prod/fullstack compose. - -**Depends on:** Phase 4 - -**Plans:** 4/4 plans complete - -Plans: -- [x] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync -- [x] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics -- [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment -- [x] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs - +**Goal:** Подготовить Matrix-бот к реальному деплою на lambda.coredump.ru с маршрутизацией по агентам и передачей файлов. +**Status:** Completed **Deliverables:** -- Space+rooms onboarding remains the primary Matrix UX -- Per-room `platform_chat_id` provides true context isolation and `!clear` -- Reconciliation restores room metadata and routing after restart -- File transfer uses shared `/agents/` volume with room-safe behavior -- `docker-compose.prod.yml` is bot-only handoff; `docker-compose.fullstack.yml` is for internal E2E testing +- Загрузка `matrix-agents.yaml` для маппинга пользователей к агентам. +- Per-room `platform_chat_id` routing. +- File transfer через shared `/agents/` volume. +- Разделение `docker-compose.prod.yml` и `docker-compose.fullstack.yml`. --- - -### Phase 3: Production Hardening - -**Goal:** Подготовить боты к реальному деплою — конфиг, логирование, мониторинг, обработка ошибок. - -**Depends on:** Phase 2 - -**Deliverables:** -- Docker / systemd конфиг для деплоя -- Структурированное логирование в production формате -- Health-check endpoint (если нужен) -- Rate limiting и защита от спама -- Graceful shutdown +*Note: Легаси-фазы, связанные с Telegram, прототипами и Mock-платформой, были удалены из Roadmap после закрепления архитектуры MVP в ветке main.* diff --git a/.planning/STATE.md b/.planning/STATE.md index eb05f42..47a860b 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,12 +2,12 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Phase 05 Paused -last_updated: "2026-04-29T08:49:04Z" +status: MVP Deployed +last_updated: "2026-05-03T23:00:00Z" progress: - total_phases: 6 + total_phases: 3 completed_phases: 3 - total_plans: 16 + total_plans: 13 completed_plans: 13 --- @@ -15,115 +15,35 @@ progress: ## Project Reference -See: .planning/PROJECT.md (updated 2026-04-02) +See: `.planning/PROJECT.md` (updated 2026-05-03) -**Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра -**Current focus:** Phase 05 paused — latest file-contract change needs a new image build before platform redeploy +**Core value:** Пользователь бесшовно взаимодействует с изолированными агентами через нативные интерфейсы (Matrix), в то время как платформа агентов не зависит от транспорта. +**Current focus:** Итерационное развитие текущей архитектуры, добавление новых фич и поверхностей (по мере необходимости). ## Current Phase -**Phase 05** paused: MVP deployment hardening is in place, but the latest attachment workspace-root change is not yet published +Текущий MVP успешно завершен. Все базовые механизмы внедрены и работают: +- Маршрутизация к `AgentApi` +- Shared Volume файловый обмен (`/agents/`) +- Dynamic config через `matrix-agents.yaml` +- Изоляция контекстов через `platform_chat_id` -Deployment handoff follow-up is external. The last published image predates the latest file-handling change; the next step is to rebuild and publish a fresh image, then ask the platform to redeploy Matrix with the shared `/agents` volumes and `config/matrix-agents.yaml`. - -Plan `05-01` is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy `platform_chat_id` bindings on restart. - -- `a75b26a` — failing restart reconciliation regressions for recovery, idempotence, startup ordering, and legacy backfill -- `8a80d00` — startup reconciliation module and pre-sync wiring in the Matrix runtime - -Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v`. - -Plan `05-02` is complete. Matrix room-local context commands now rely on repaired per-room `platform_chat_id` bindings, and `!clear` rotates only the active room's upstream context when prototype room state is available. - -- `ae37476` — failing regressions for clear registration, room-local rotation, and strict routed-platform metadata requirements -- `85e2fda` — room-local clear semantics, compatibility alias wiring, and strict context resolution without shared chat fallbacks - -Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v`. - -Plan `05-03` is complete. Shared-volume attachment handling now preserves relative agent paths while tolerating both `/workspace` and `/agents` absolute prefixes during normalization and Matrix file rendering. - -- `7a12a71` — failing regressions for shared-volume path normalization and room-safe attachment handling -- `5eddf16` — `/agents` deployment path hardening for Matrix files and routed platform attachments - -Verified with `uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. - -Plan `05-04` is complete. Production handoff now uses `docker-compose.prod.yml` for a bot-only runtime, while internal end-to-end verification uses `docker-compose.fullstack.yml` with shared `/agents` volume guidance and health-gated startup. - -- `df6d8bf` — split prod and full-stack compose artifacts with the shared `/agents` contract -- `22a3a2b` — operator and deployment docs aligned to the split compose artifacts - -Verified with `docker compose -f docker-compose.prod.yml config`, `docker compose -f docker-compose.fullstack.yml config`, and docs grep checks for `docker-compose.prod.yml`, `docker-compose.fullstack.yml`, and `/agents`. +Проект находится в чистом состоянии для начала нового планирования. Неактуальные легаси фазы и прототипы (Telegram, MockPlatformClient) удалены из Roadmap и трекинга. ## Decisions -- Продолжаем с Threaded Mode несмотря на баги Mac клиента (2026-04-02) -- Invite flow Matrix переведён на idempotent-проверку через `user_meta.space_id`, а не через invite-room metadata (2026-04-02) -- Неизвестные Matrix rooms больше не auto-register в роутере; используется явный fallback `unregistered:{room_id}` с warning-логом (2026-04-02) -- [Phase 01]: Use ChatContext.surface_ref as the Matrix room identifier for !rename updates. -- [Phase 01]: Keep !archive limited to core archive state in Phase 1; Space child removal remains deferred. -- [Phase 01]: Matrix OutgoingUI no longer emits reactions; confirmation state is persisted and resumed via `!yes` / `!no`. -- [Phase 01]: `!settings` now renders a dashboard snapshot instead of advertising mutable subcommands. -- [Phase 01]: Split Matrix regression coverage into dedicated invite/chat/send_outgoing/confirm test modules. -- [Phase 01]: Kept 01-04 scoped to test coverage without widening into production-code changes. -- [Phase 01]: Matrix command callbacks now include room_id in payload for !yes and !no so confirm handlers can resolve runtime state without changing core protocol types. -- [Phase 01]: Pending confirmations are stored under the D-08 composite key of matrix user id plus room id, with a narrow legacy fallback only for callers that omit room context. -- [Phase 01]: Removed Matrix reaction conversion entirely and kept command callbacks limited to !yes/!no. -- [Phase 01]: Kept !settings as a pure snapshot surface while preserving mutable subcommands outside the dashboard. -- [Phase 01]: Seeded invite and dispatcher tests with explicit next_chat_index and room ids instead of treating C1 as Matrix transport identity. -- [Phase 04]: Replaced AgentSessionClient with AgentApiWrapper and persistent agent connection lifecycle in Matrix runtime. -- [Phase 04]: Added !save, !load, !reset, and !context commands with pending-state interception and local prototype session metadata. -- [Phase 04]: Added Matrix-only Docker packaging for MVP deployment; platform services remain external to this compose setup. -- [Phase 04]: Replaced the Matrix prod path again with direct upstream `AgentApi` per request; removed the local runtime wrapper from the prod flow. -- [Phase 04]: Adopted `AGENT_BASE_URL` as the primary runtime contract and kept `AGENT_WS_URL` only as backward-compatible env fallback. -- [Phase 04 follow-up]: Kept shared PlatformClient unchanged; introduced Matrix-specific RoutedPlatformClient to avoid breaking Telegram adapter. -- [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient). -- [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata. -- [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test. -- [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts. -- [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references. -- [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering. -- [Phase 05]: Treat synced Matrix topology as authoritative for startup recovery; keep SQLite rebuildable. -- [Phase 05]: Backfill missing platform_chat_id values during startup reconciliation before routed handling begins. -- [Phase 05]: Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias. -- [Phase 05]: Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids. -- [Phase 05]: Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification. -- [Phase 05]: Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same named volume. +- **Space+rooms для Matrix**: Разделение тредов на отдельные Matrix-комнаты, собранные в едином Space пользователя. +- **AgentApi**: Прямая интеграция с локальным агентом без Master-прослойки по WebSocket. +- **Shared Volume**: Файлы кладутся напрямую в рабочую папку агента, избавляя от необходимости гонять их по сети в Base64. +- **Статическая маршрутизация**: На данном этапе пользователи маппятся на агентов жестко через YAML. ## Blockers -- Lambda platform SDK не готов — Phase 2 заблокирована до готовности платформы -- Full production verification depends on the platform team's real multi-agent orchestration, production Matrix credentials, `config/matrix-agents.yaml`, and shared `/agents/N` volume mounts. +- Отсутствуют. Проект готов к деплою (см. `docker-compose.prod.yml`). ## Accumulated Context ### Roadmap Evolution -- Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT) -- Phase 4 added: Matrix MVP: shared agent context and context management command -- Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence) -- Phase 05 reset on 2026-04-28: erroneous single-chat deployment artifacts were removed before fresh planning. - -## Performance Metrics - -| Phase | Plan | Duration | Tasks | Files | Recorded | -| --- | --- | --- | --- | --- | --- | -| 01 | 01 | 1 min | 3 | 3 | 2026-04-02T19:50:50Z | -| 01 | 02 | 1 min | 2 | 2 | 2026-04-02 | -| 01 | 03 | 3 min | 2 | 5 | 2026-04-02T19:57:34Z | -| 01 | 04 | 3 min | 2 | 7 | 2026-04-02T20:03:38Z | -| 01 | 05 | 2 min | 2 | 7 | 2026-04-03T09:28:47Z | -| 01 | 06 | 4 min | 2 | 7 | 2026-04-03T09:35:47Z | -| 04 | 01 | 1 session | 1 wave | 8 | 2026-04-17 | -| 04 | 02 | 1 session | 2 commits + summary | 8 | 2026-04-17 | -| 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | -| 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | -| 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | -| 05 | 01 | 8 min | 2 | 4 | 2026-04-27T22:09:28Z | -| 05 | 02 | 16 min | 2 | 4 | 2026-04-27T22:15:58Z | -| 05 | 04 | 3 min | 2 | 5 | 2026-04-27T22:17:10Z | - -## Session - -- Last session: 2026-04-29T08:49:04Z -- Stopped at: Handoff updated after attachment workspace-root change; waiting for image rebuild and platform redeploy -- Resume file: .planning/phases/05-mvp-deployment/.continue-here.md +- Изначальный Roadmap включал множество ответвлений (прототипы Telegram, локальный mock-клиент). После закрепления MVP в `main` Roadmap был очищен, чтобы отражать только актуальный путь продукта. +- Следующие фазы будут добавляться по мере возникновения новых задач (например, переход от YAML-конфига к БД для реестра агентов). diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md deleted file mode 100644 index 6de8f62..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow -task: 1 -total_tasks: 2 -status: paused -last_updated: 2026-04-07T21:29:48.982Z ---- - - -Formally, the most recently active execution artifact inside the roadmap is still `01.1-03-PLAN.md`, which has not been implemented yet. In parallel, the platform-integration track has moved forward: the direct-agent Matrix prototype design is now approved, the implementation plan is written, and the next useful session should evaluate that spec/plan pair against the live platform repos before starting execution. - - - - -- Re-analysed live platform repos on 2026-04-07 by cloning `platform/agent`, `platform/agent_api`, `platform/master`, and `platform/docs`. -- Confirmed `master` is still only a thin HTTP skeleton with `/health` and `/users/{user_id}`, not a chat/session/settings backend for surfaces. -- Confirmed `agent` exposes a working `/agent_ws/` WebSocket and `agent_api` provides enough protocol/client code to stream model output. -- Identified the real technical gap for a prototype: `agent` currently uses a singleton service with a fixed `thread_id="default"`, so all conversations would share memory unless that is parameterized. -- Derived and got approval for the prototype path: keep Matrix adapter logic largely intact, add `sdk/agent_session.py`, `sdk/prototype_state.py`, and `sdk/real.py`, keep settings local, and use the direct `agent` WebSocket for real messaging. -- Resolved the repo-placement question: the prototype stays in this repo on its own branch, not in a separate prototype repo. -- Resolved the platform-change minimization question: prefer patching only `platform/agent`, not `platform/agent_api`, and use a tiny local WebSocket client in this repo. -- Wrote and committed the approved design spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`. -- Wrote the implementation plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`. - - - - -- Task 1: Implement `adapter.matrix.reset` with `local-only`, `server-leave-forget`, and `--dry-run`, plus tests. -- Task 2: Update `README.md` so restart vs explicit reset workflow is documented and the old manual reset ritual is removed. -- Prototype evaluation follow-up: review the approved spec and plan against the platform repos before starting execution. -- Future prototype work: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split. - - - - -- Do not integrate with `master` yet; it is still not the backend surfaces needs. -- Use the direct `agent` WebSocket as the only realistic path for a working prototype right now. -- Keep consumer-facing Matrix logic as intact as possible and absorb backend differences inside a shim under `sdk/`. -- Treat future platform evolution as likely to split into at least two concerns: control-plane access and direct agent session streaming. -- Keep the prototype in this repo on its own branch. -- Minimize platform-side changes by patching only `platform/agent` if possible. - - - -- Phase 01.1 itself is not blocked; it is simply paused. -- Prototype blocker: the `agent` repo currently hardcodes a shared `thread_id`, so per-user/per-chat conversation isolation requires either a small upstream change or a careful workaround. -- Platform contract blocker remains for the longer-term Phase 02 direction: `master` still lacks stable user/chat/session/settings APIs for surfaces. - - - -The important mental model is now stable enough to execute. Full SDK integration through `master` is still premature, but a working Matrix prototype can be built now by talking directly to the `agent` WebSocket and hiding the split backend reality behind `sdk/real.py`. The approved design keeps the prototype in this repo, keeps settings local, and minimizes platform changes by preferring a tiny `platform/agent` patch over broader protocol churn. For evaluation and implementation context, inspect: -- local spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md` -- local plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md` -- remote repos: `https://git.lambda.coredump.ru/platform/agent`, `https://git.lambda.coredump.ru/platform/master`, `https://git.lambda.coredump.ru/platform/agent_api` -- local clones: `/tmp/platform-agent`, `/tmp/platform-master`, `/tmp/platform-agent_api` - - - -Resume with one of these depending on priority: -1. Evaluate the approved prototype spec and implementation plan against the live platform repos and decide whether to start in this repo or patch `platform/agent` first. -2. If staying on roadmap execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first. -3. If starting prototype execution immediately, begin with Task 1 of `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`. - diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.gitkeep b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-01-PLAN.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-01-PLAN.md deleted file mode 100644 index 187baa9..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-01-PLAN.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow -plan: 01 -type: execute -wave: 1 -depends_on: [] -files_modified: - - adapter/matrix/reconcile.py - - tests/adapter/matrix/test_reconcile.py -autonomous: true -requirements: [] - -must_haves: - truths: - - "A normal Matrix restart can rebuild missing local metadata from already joined Space/chat rooms instead of requiring a destructive reset." - - "Reconciliation restores the minimal local state needed for routing and chat operations: `matrix_user:*`, `matrix_room:*`, and missing `chat:{user}:{chat_id}` rows." - - "Reconciliation never provisions new Matrix rooms or Spaces while repairing local state." - - "Recovered users get `next_chat_index` advanced past the highest recovered `C*` chat id." - artifacts: - - path: "adapter/matrix/reconcile.py" - provides: "Matrix bootstrap reconciliation helpers and structured report objects." - - path: "tests/adapter/matrix/test_reconcile.py" - provides: "Regression coverage for startup and single-room reconciliation behavior." - key_links: - - from: "adapter/matrix/reconcile.py" - to: "adapter/matrix/store.py" - via: "set_user_meta and set_room_meta restore Matrix metadata" - pattern: "set_(user|room)_meta" - - from: "adapter/matrix/reconcile.py" - to: "core/chat.py" - via: "chat_mgr.get_or_create repairs missing `chat:*` rows" - pattern: "chat_mgr\\.get_or_create" ---- - - -Create the non-destructive Matrix reconciliation layer that Phase 01.1 depends on. - -Purpose: Per D-01 through D-07, the adapter must stop treating local SQLite state as the only truth in dev. Startup and recovery code need a single helper module that can rebuild local metadata from the homeserver room graph without creating duplicate Spaces or chats. -Output: `adapter/matrix/reconcile.py` with full-run and single-room recovery helpers, plus targeted pytest coverage. - - - -@/Users/a/.codex/get-shit-done/workflows/execute-plan.md -@/Users/a/.codex/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md -@.planning/phases/01-matrix-qa-polish/01-01-SUMMARY.md -@adapter/matrix/store.py -@adapter/matrix/handlers/auth.py -@core/chat.py -@tests/adapter/matrix/test_invite_space.py - - -From `adapter/matrix/store.py`: - -```python -async def get_room_meta(store: StateStore, room_id: str) -> dict | None -async def set_room_meta(store: StateStore, room_id: str, meta: dict) -> None -async def get_user_meta(store: StateStore, matrix_user_id: str) -> dict | None -async def set_user_meta(store: StateStore, matrix_user_id: str, meta: dict) -> None -``` - -From `core/chat.py`: - -```python -async def get_or_create( - self, - user_id: str, - chat_id: str, - platform: str, - surface_ref: str, - name: str | None = None, -) -> ChatContext -``` - -From Phase 01 room metadata shape: - -```python -{ - "room_type": "chat", - "chat_id": "C4", - "display_name": "Чат 4", - "matrix_user_id": "@alice:example.org", - "space_id": "!space:example.org", -} -``` - - - - - - - Task 1: Add reconciliation module for startup and single-room recovery - adapter/matrix/reconcile.py, tests/adapter/matrix/test_reconcile.py - adapter/matrix/store.py, adapter/matrix/handlers/auth.py, core/chat.py, tests/adapter/matrix/test_invite_space.py, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md - - - Test 1: `reconcile_matrix_state(...)` recreates missing `matrix_user:*`, `matrix_room:*`, and `chat:*` entries from joined Matrix rooms without calling `room_create`. - - Test 2: `reconcile_matrix_state(...)` leaves already-correct local metadata intact and reports restored vs skipped/conflicting rooms. - - Test 3: `reconcile_single_room(...)` can repair one `unregistered:{room_id}` chat room on demand and recompute `next_chat_index` for that user. - - Test 4: Space rooms or unrelated joined rooms are skipped, not converted into chat rows. - - -Create `adapter/matrix/reconcile.py` as the authoritative recovery module for this phase. Implement a small, explicit API that Plan 02 can wire directly: - -```python -async def reconcile_matrix_state(client: Any, store: StateStore, chat_mgr: ChatManager) -> dict: ... -async def reconcile_single_room( - client: Any, store: StateStore, chat_mgr: ChatManager, room_id: str, matrix_user_id: str -) -> dict: ... -``` - -Inside this module, add focused private helpers as needed for room classification, extracting room names, parsing `C` ids, and recomputing `next_chat_index`. Keep the logic non-destructive per D-04: -- never call `room_create`, `room_invite`, or provisioning code from `handlers/auth.py` -- prefer already-hydrated room data from the post-sync client object, and only fall back to explicit room-state fetches if required for room classification -- rebuild only the minimal metadata required by D-03: `matrix_user:*`, `matrix_room:*`, and missing `chat:{user}:{chat_id}` records -- if `chat:*` exists but points at the wrong `surface_ref`, repair it from Matrix room metadata and include the fix in the returned report -- derive `next_chat_index` from the highest recovered `C` for that user instead of trusting stale local counters - -Return a structured reconciliation report with stable keys such as: -`joined_rooms`, `restored_user_meta`, `restored_room_meta`, `restored_chat_rows`, `repaired_chat_rows`, `skipped_rooms`, and `conflicts`. - -Write `tests/adapter/matrix/test_reconcile.py` with lightweight `SimpleNamespace`/fake-client fixtures following the existing Matrix test style. Cover both full startup reconciliation and `reconcile_single_room(...)`. Assert that no provisioning calls are made during reconciliation, because D-04 forbids creating new Space/room topology while recovering local state. - - - cd /Users/a/MAI/sem2/lambda/surfaces-bot && pytest tests/adapter/matrix/test_reconcile.py -q - - - - `adapter/matrix/reconcile.py` exports `reconcile_matrix_state` and `reconcile_single_room`. - - Reconciliation restores missing `matrix_user:*`, `matrix_room:*`, and `chat:*` entries for already-joined Matrix chat rooms per D-02 and D-03. - - Reconciliation does not call `room_create` or otherwise provision new server-side rooms per D-04. - - The report returned by reconciliation clearly distinguishes restored items, skipped rooms, and conflicts. - - `tests/adapter/matrix/test_reconcile.py` proves `next_chat_index` is recomputed from recovered chat ids rather than stale local state. - - The repository has an executable, tested reconciliation layer that can rebuild local Matrix metadata after dev-state loss without duplicating server-side rooms. - - - - - -Run `pytest tests/adapter/matrix/test_reconcile.py -q` and confirm startup and single-room reconciliation paths are covered. - - - -- Matrix recovery logic exists as a dedicated module instead of being scattered through handlers. -- Reconciliation is idempotent, non-destructive, and sufficient to restore routing/chat metadata from existing Matrix rooms. -- Plan 02 can wire startup and first-access recovery by calling exported functions rather than inventing new recovery logic. - - - -After completion, create `.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-01-SUMMARY.md` - diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-02-PLAN.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-02-PLAN.md deleted file mode 100644 index bdfdaf8..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-02-PLAN.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow -plan: 02 -type: execute -wave: 2 -depends_on: ["01.1-01"] -files_modified: - - adapter/matrix/bot.py - - tests/adapter/matrix/test_dispatcher.py -autonomous: true -requirements: [] - -must_haves: - truths: - - "The Matrix bot performs an initial sync and reconciliation before entering steady-state `sync_forever()`." - - "If a room still arrives as `unregistered:{room_id}` after startup, the bot makes one targeted recovery attempt before dispatching or failing." - - "When reconciliation cannot repair a room, the bot logs a clear diagnostic reason instead of crashing on downstream commands like `!rename`." - artifacts: - - path: "adapter/matrix/bot.py" - provides: "Startup bootstrap flow with initial sync, reconciliation, and targeted runtime retry." - - path: "tests/adapter/matrix/test_dispatcher.py" - provides: "Matrix runtime coverage for pre-sync reconcile and on-message recovery behavior." - key_links: - - from: "adapter/matrix/bot.py" - to: "adapter/matrix/reconcile.py" - via: "startup bootstrap and single-room recovery calls" - pattern: "reconcile_(matrix_state|single_room)" - - from: "adapter/matrix/bot.py" - to: "adapter/matrix/room_router.py" - via: "unregistered room detection before dispatch" - pattern: "unregistered:" ---- - - -Wire the new reconciliation layer into the actual Matrix runtime. - -Purpose: D-05 through D-07 require restart recovery to be the default developer path. The bot must bootstrap itself from existing Matrix rooms on startup and make one on-demand repair attempt before routing an unknown room through the dispatcher. -Output: `adapter/matrix/bot.py` performs initial sync + reconciliation before `sync_forever()`, and runtime tests prove the bot recovers or logs clearly instead of blindly dispatching broken state. - - - -@/Users/a/.codex/get-shit-done/workflows/execute-plan.md -@/Users/a/.codex/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-01-PLAN.md -@adapter/matrix/bot.py -@adapter/matrix/room_router.py -@adapter/matrix/reconcile.py -@tests/adapter/matrix/test_dispatcher.py - - -From `adapter/matrix/bot.py`: - -```python -class MatrixBot: - async def on_room_message(self, room: MatrixRoom, event: RoomMessageText) -> None - -async def main() -> None -``` - -From `adapter/matrix/reconcile.py`: - -```python -async def reconcile_matrix_state(client: Any, store: StateStore, chat_mgr: ChatManager) -> dict -async def reconcile_single_room( - client: Any, store: StateStore, chat_mgr: ChatManager, room_id: str, matrix_user_id: str -) -> dict -``` - -From `adapter/matrix/room_router.py`: - -```python -async def resolve_chat_id(store: StateStore, room_id: str, matrix_user_id: str) -> str -``` - - - - - - - Task 1: Run initial sync and reconciliation before the long-poll loop - adapter/matrix/bot.py, tests/adapter/matrix/test_dispatcher.py - adapter/matrix/bot.py, adapter/matrix/reconcile.py, tests/adapter/matrix/test_dispatcher.py, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md - - - Test 1: `main()` performs `client.sync(timeout=0, full_state=True)` before `sync_forever()`. - - Test 2: `main()` calls `reconcile_matrix_state(...)` after the initial sync and logs the returned report. - - Test 3: startup still reaches `sync_forever()` when reconciliation reports recoverable skips/conflicts instead of fatal failure. - - -Modify `adapter/matrix/bot.py` so normal startup follows the two-phase bootstrap recommended in research: -1. build client and runtime -2. authenticate -3. register callbacks -4. run `await client.sync(timeout=0, full_state=True)` -5. run `await reconcile_matrix_state(client, runtime.store, runtime.chat_mgr)` -6. log a structured `matrix_reconcile_complete` event with the report fields -7. enter `await client.sync_forever(timeout=30000)` - -Do not move provisioning logic into startup. The startup step only rehydrates local state from server-side rooms per D-02 through D-04. - -Update or add focused tests in `tests/adapter/matrix/test_dispatcher.py` using `monkeypatch`/fake-client patterns already used in the repo so the verify command proves the call order and logging-safe behavior. The test should fail if `sync_forever()` starts before reconciliation. - - - cd /Users/a/MAI/sem2/lambda/surfaces-bot && pytest tests/adapter/matrix/test_dispatcher.py -q - - - - `adapter/matrix/bot.py` runs an initial full-state sync before steady-state polling. - - `adapter/matrix/bot.py` invokes `reconcile_matrix_state(...)` exactly once during startup. - - Startup logs a structured reconciliation summary instead of silently skipping the recovery step. - - `tests/adapter/matrix/test_dispatcher.py` asserts the bootstrap order explicitly. - - Normal Matrix bot startup now includes a recovery pass before the event loop begins handling user traffic. - - - - Task 2: Retry unknown-room routing once before dispatching broken state - adapter/matrix/bot.py, tests/adapter/matrix/test_dispatcher.py - adapter/matrix/bot.py, adapter/matrix/room_router.py, adapter/matrix/reconcile.py, tests/adapter/matrix/test_dispatcher.py, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md - - - Test 1: `MatrixBot.on_room_message(...)` detects `unregistered:{room_id}`, runs `reconcile_single_room(...)`, then retries `resolve_chat_id(...)`. - - Test 2: if retry succeeds, the event is dispatched against the recovered logical chat id. - - Test 3: if retry still fails, the bot does not crash; it logs a clear warning and sends a user-facing diagnostic message to that room. - - -Extend `MatrixBot.on_room_message(...)` so D-07 is satisfied even when startup could not repair a room yet. Keep `resolve_chat_id(...)` as the room-router source of truth, but treat `unregistered:{room_id}` as a recovery trigger rather than a stable runtime identity: -- first call `resolve_chat_id(...)` -- if the result starts with `unregistered:`, call `reconcile_single_room(client, runtime.store, runtime.chat_mgr, room.room_id, event.sender)` -- immediately retry `resolve_chat_id(...)` -- only dispatch once a concrete logical chat id exists -- if the retry still returns `unregistered:{room_id}`, log a structured warning with room id, matrix user id, and reconciliation report, then send a short `OutgoingMessage`-equivalent Matrix text explaining that local state could not be restored automatically and a dev reset/restart may be required - -Do not invent a new fallback chat id and do not auto-create rooms here; that would violate D-04. Keep this change inside `adapter/matrix/bot.py` so file ownership stays isolated for this plan. - - - cd /Users/a/MAI/sem2/lambda/surfaces-bot && pytest tests/adapter/matrix/test_dispatcher.py -q - - - - Unknown Matrix rooms trigger one targeted reconciliation attempt before dispatch. - - Successful targeted recovery leads to normal dispatch with a real logical `chat_id`. - - Failed targeted recovery logs a clear diagnostic and avoids a handler crash on missing chat state per D-06. - - No code path in this task provisions new Matrix rooms or Spaces. - - The runtime treats unknown rooms as recoverable state drift first, not as a silent routing failure or crash path. - - - - - -Run `pytest tests/adapter/matrix/test_dispatcher.py -q` and confirm both startup-bootstrap and first-access recovery behaviors are covered. - - - -- A standard Matrix restart now attempts recovery before the bot starts processing live events. -- Unknown-room events are diagnosable and recoverable instead of falling straight into broken command handling. -- The runtime never provisions new server-side rooms during restart reconciliation. - - - -After completion, create `.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-02-SUMMARY.md` - diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-PLAN.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-PLAN.md deleted file mode 100644 index bd78891..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-PLAN.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow -plan: 03 -type: execute -wave: 1 -depends_on: [] -files_modified: - - adapter/matrix/reset.py - - tests/adapter/matrix/test_reset.py - - README.md -autonomous: true -requirements: [] - -must_haves: - truths: - - "Developers have an explicit dev-only reset command instead of relying on memory or ad hoc shell history." - - "The default reset mode clears only local Matrix state and explains the manual Matrix-client cleanup that may still be needed." - - "Optional server cleanup is clearly named around leave/forget semantics and supports dry-run output." - artifacts: - - path: "adapter/matrix/reset.py" - provides: "Dev reset CLI for local-only, server-leave-forget, and dry-run workflows." - - path: "tests/adapter/matrix/test_reset.py" - provides: "CLI coverage for local reset behavior and printed operator guidance." - - path: "README.md" - provides: "Updated developer instructions for normal restart vs explicit reset." - key_links: - - from: "adapter/matrix/reset.py" - to: "README.md" - via: "documented invocation and manual Matrix cleanup guidance" - pattern: "adapter\\.matrix\\.reset" ---- - - -Ship the dev reset workflow that complements normal restart reconciliation. - -Purpose: D-08 through D-10 require a repeatable, explicit reset path for clean-room QA without making destructive cleanup the default restart flow. This plan creates the tool and updates the runbook developers actually use. -Output: `adapter/matrix/reset.py`, pytest coverage, and README instructions that replace the old `rm -f lambda_matrix.db` ritual. - - - -@/Users/a/.codex/get-shit-done/workflows/execute-plan.md -@/Users/a/.codex/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md -@.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md -@README.md -@adapter/matrix/bot.py -@core/store.py - - -From `adapter/matrix/bot.py` env usage: - -```python -db_path = os.environ.get("MATRIX_DB_PATH", "lambda_matrix.db") -store_path = os.environ.get("MATRIX_STORE_PATH", "matrix_store") -homeserver = os.environ.get("MATRIX_HOMESERVER") -user_id = os.environ.get("MATRIX_USER_ID") -``` - -From `core/store.py`: - -```python -class SQLiteStore: - def __init__(self, db_path: str) -> None: ... -``` - - - - - - - Task 1: Add a dev-only Matrix reset CLI with explicit modes - adapter/matrix/reset.py, tests/adapter/matrix/test_reset.py - adapter/matrix/bot.py, core/store.py, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md - - - Test 1: `--mode local-only` deletes the configured local DB/store paths or reports what would be deleted in dry-run mode. - - Test 2: `--mode server-leave-forget --dry-run` prints the exact rooms it would leave/forget and does not mutate local files. - - Test 3: when server cleanup is not executed, the command prints the manual Matrix-client steps required by D-10. - - -Create `adapter/matrix/reset.py` as a CLI entrypoint runnable via `uv run python -m adapter.matrix.reset`. Use `argparse` and keep the tool explicitly dev-only in its help text and logs. - -Implement the following modes from research and locked decisions: -- `local-only` (default destructive mode for local QA): remove `MATRIX_DB_PATH` and `MATRIX_STORE_PATH` if they exist; if not, report that they were already absent -- `server-leave-forget`: for the bot account only, log in using the same Matrix env vars as `adapter/matrix/bot.py`, inspect joined rooms, and call `room_leave()` + `room_forget()` for each joined room; support `--dry-run` so the operator can inspect the target set before mutation -- `--dry-run` must work with both modes and print a structured summary instead of mutating files or Matrix membership - -Always print a post-run summary that distinguishes: -- what local files/directories were deleted or would be deleted -- what server-side leave/forget actions were executed or would be executed -- the manual Matrix client steps still required for a true clean-room QA rerun (leave/archive old rooms or Space in Element, accept fresh invites, etc.) when those actions are outside this phase - -Write `tests/adapter/matrix/test_reset.py` to cover local-only deletion, dry-run output, and server-leave-forget dry-run behavior with fake clients/temporary directories. Follow the repo’s existing lightweight async test style. - - - cd /Users/a/MAI/sem2/lambda/surfaces-bot && pytest tests/adapter/matrix/test_reset.py -q - - - - `adapter/matrix/reset.py` supports `local-only`, `server-leave-forget`, and `--dry-run`. - - `local-only` reset targets both `lambda_matrix.db` and `matrix_store` via env-aware paths per D-09. - - The tool never claims to globally delete Matrix rooms; it uses leave/forget semantics or prints manual cleanup instructions per D-10. - - `tests/adapter/matrix/test_reset.py` proves dry-run mode is non-destructive. - - The repository contains a repeatable dev reset tool that replaces the undocumented shell ritual and names server-side cleanup honestly. - - - - Task 2: Replace the README reset ritual with the new restart and reset workflow - README.md - README.md, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md, .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md - -Update `README.md` so Matrix development instructions reflect Phase 01.1 instead of the old destructive reset ritual. Replace the current manual QA block that tells developers to `rm -f lambda_matrix.db` with a short, explicit split: -- normal restart: `PYTHONPATH=. uv run python -m adapter.matrix.bot` now performs reconciliation automatically -- explicit clean-room reset: `PYTHONPATH=. uv run python -m adapter.matrix.reset --mode local-only` -- optional server cleanup preview: `PYTHONPATH=. uv run python -m adapter.matrix.reset --mode server-leave-forget --dry-run` - -State clearly that normal restart is the default path per D-05, and that full server-side cleanup may still require manual steps in the Matrix client. Keep the README concise; do not add production guidance or Phase 2 SDK content. - - - cd /Users/a/MAI/sem2/lambda/surfaces-bot && python -m adapter.matrix.reset --help >/tmp/matrix-reset-help.txt && rg -n "adapter.matrix.reset|local-only|server-leave-forget|reconciliation" README.md /tmp/matrix-reset-help.txt - - - - `README.md` no longer recommends raw `rm -f lambda_matrix.db` as the default Matrix restart workflow. - - `README.md` documents the normal restart path and the explicit reset path separately. - - The documented reset commands match the CLI implemented in `adapter/matrix/reset.py`. - - Developers can follow a repeatable README workflow for ordinary restart and clean-room QA reset without relying on tribal knowledge. - - - - - -Run `pytest tests/adapter/matrix/test_reset.py -q` and `python -m adapter.matrix.reset --help`, then confirm the README commands and help text stay aligned. - - - -- Dev reset is an explicit tool, not a remembered shell sequence. -- Local-only reset is automated and documented. -- Server cleanup semantics are honest, dry-runnable, and accompanied by manual Matrix-client guidance where needed. - - - -After completion, create `.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-03-SUMMARY.md` - diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md deleted file mode 100644 index 665061e..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md +++ /dev/null @@ -1,121 +0,0 @@ -# Phase 01.1: Matrix restart reconciliation and dev reset workflow - Context - -**Gathered:** 2026-04-03 -**Status:** Ready for planning - - -## Phase Boundary - -Сделать Matrix-адаптер пригодным для повторяемой локальной разработки и ручного QA без ручного “ритуала” удаления БД, выхода из всех комнат и пересоздания пользователя. - -В scope этой фазы: -- безопасный restart flow для Matrix-бота после потери локального state -- reconciliation локального store с уже существующими Matrix rooms / Space -- отдельный dev reset workflow для controlled clean-room QA -- диагностируемое поведение при несогласованности local state и server-side Matrix state - -Вне scope: -- реальный Lambda SDK -- новые пользовательские Matrix features -- E2EE -- production-grade multi-user migration framework - - - - -## Implementation Decisions - -### Matrix state lifecycle - -- **D-01:** Локальный SQLite store больше не должен считаться единственной точкой истины для Matrix runtime в dev workflow. -- **D-02:** При старте бот должен пытаться восстановить минимально необходимое локальное состояние из уже существующих Matrix rooms / Space, а не требовать full reset. -- **D-03:** Reconciliation должен восстанавливать как минимум `matrix_user:*`, `matrix_room:*` и missing `chat:{user}:{chat_id}` записи, если серверные комнаты уже существуют. -- **D-04:** Reconciliation не должен создавать новые Space/rooms, если задача — именно восстановление локального state после рестарта. - -### Dev restart behavior - -- **D-05:** Обычный restart бота должен быть основным путём для разработки; удаление `lambda_matrix.db` и `matrix_store` не должно быть обязательным для проверки workflow. -- **D-06:** Если local state неполон, бот должен либо восстановить его, либо логировать понятную причину, а не падать на командах вроде `!rename`. -- **D-07:** Несогласованность между `room_meta` и `ChatManager` должна обнаруживаться и устраняться автоматически на startup или при первом обращении. - -### Dev reset workflow - -- **D-08:** Нужен отдельный dev-only reset tool/script для controlled QA, вместо ручного набора shell-команд. -- **D-09:** Reset workflow должен как минимум поддерживать `local-only` reset: удаление `lambda_matrix.db` и `matrix_store` с понятной инструкцией, что делать с server-side Matrix rooms. -- **D-10:** Если full server-side cleanup не автоматизируется в этой фазе, tool должен явно печатать, какие ручные шаги обязательны в Matrix client. - -### The agent's Discretion - -- Точное место вызова reconciliation в startup flow -- Внутренняя структура helper-модуля (`bootstrap.py`, `reconcile.py` или аналог) -- Формат dev reset script и уровень автоматизации server-side cleanup -- Детали debug-logging и dry-run режима, если они помогают без раздувания scope - - - - -## Specific Ideas - -- Главный критерий: после обычного restart бот не должен ломаться только потому, что local DB была сброшена или частично потеряна. -- Reset workflow должен быть явным и repeatable, а не завязанным на память разработчика. -- Нужно различать две ситуации: - - broken because code is wrong - - broken because local dev state was deliberately reset and requires reconciliation - - - - -## Canonical References - -**Downstream agents MUST read these before planning or implementing.** - -### Matrix phase artifacts -- `.planning/phases/01-matrix-qa-polish/01-CONTEXT.md` — locked Matrix decisions from Phase 1 -- `.planning/phases/01-matrix-qa-polish/01-VERIFICATION.md` — what Phase 1 already validated and what manual QA still expects -- `.planning/phases/01-matrix-qa-polish/01-HUMAN-UAT.md` — remaining real-client Matrix checks - -### Current Matrix runtime -- `adapter/matrix/bot.py` — startup flow, sync loop, runtime wiring, DB/store env vars -- `adapter/matrix/store.py` — persisted Matrix metadata and pending confirmation keys -- `adapter/matrix/room_router.py` — room_id to chat_id resolution and current unregistered fallback -- `adapter/matrix/handlers/auth.py` — invite bootstrap that creates Space and first chat room -- `core/chat.py` — `ChatManager` persistence contract that currently breaks when local state is missing - -### Supporting docs -- `docs/matrix-prototype.md` — intended Matrix UX and architecture direction -- `README.md` — current run instructions and existing manual QA/reset habits - - - - -## Existing Code Insights - -### Reusable Assets -- `adapter/matrix/store.py` already persists room/user metadata and is the obvious place to anchor reconciliation inputs. -- `adapter/matrix/room_router.py` already detects unknown rooms via `unregistered:{room_id}` fallback; this is a useful reconciliation trigger point. -- `core/chat.py` already has `get_or_create`, `rename`, `archive`, `list_active`; missing chat records can be rebuilt through this API instead of inventing a parallel format. - -### Established Patterns -- Matrix runtime uses `SQLiteStore` for adapter-local metadata and `matrix-nio` room callbacks for transport events. -- Phase 1 already moved Matrix to Space+rooms and command-only confirmations, so this phase must preserve that model rather than reverting to DM-first simplifications. - -### Integration Points -- Startup path in `adapter/matrix/bot.py:main()` is the natural place to run reconciliation before `sync_forever`. -- Invite/bootstrap path in `adapter/matrix/handlers/auth.py` is the existing source of truth for what metadata a healthy first room should have. -- `ChatManager` records and `matrix_room:*` metadata must stay consistent enough that commands like `!rename`, `!archive`, and `!chats` work after restart. - - - - -## Deferred Ideas - -- Full production-grade migration of historical Matrix state across schema versions -- Automatic server-side deletion/leave for all Matrix rooms and Space during reset, if it requires broader admin semantics -- Any Phase 2 SDK integration work - - - ---- - -*Phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow* -*Context gathered: 2026-04-03* diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md deleted file mode 100644 index 792031d..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-RESEARCH.md +++ /dev/null @@ -1,350 +0,0 @@ -# Phase 01.1: Matrix restart reconciliation and dev reset workflow - Research - -**Researched:** 2026-04-03 -**Domain:** Matrix adapter restart reconciliation, local state recovery, dev reset workflow -**Confidence:** HIGH - - -## User Constraints (from CONTEXT.md) - -### Locked Decisions -- **D-01:** Локальный SQLite store больше не должен считаться единственной точкой истины для Matrix runtime в dev workflow. -- **D-02:** При старте бот должен пытаться восстановить минимально необходимое локальное состояние из уже существующих Matrix rooms / Space, а не требовать full reset. -- **D-03:** Reconciliation должен восстанавливать как минимум `matrix_user:*`, `matrix_room:*` и missing `chat:{user}:{chat_id}` записи, если серверные комнаты уже существуют. -- **D-04:** Reconciliation не должен создавать новые Space/rooms, если задача — именно восстановление локального state после рестарта. -- **D-05:** Обычный restart бота должен быть основным путём для разработки; удаление `lambda_matrix.db` и `matrix_store` не должно быть обязательным для проверки workflow. -- **D-06:** Если local state неполон, бот должен либо восстановить его, либо логировать понятную причину, а не падать на командах вроде `!rename`. -- **D-07:** Несогласованность между `room_meta` и `ChatManager` должна обнаруживаться и устраняться автоматически на startup или при первом обращении. -- **D-08:** Нужен отдельный dev-only reset tool/script для controlled QA, вместо ручного набора shell-команд. -- **D-09:** Reset workflow должен как минимум поддерживать `local-only` reset: удаление `lambda_matrix.db` и `matrix_store` с понятной инструкцией, что делать с server-side Matrix rooms. -- **D-10:** Если full server-side cleanup не автоматизируется в этой фазе, tool должен явно печатать, какие ручные шаги обязательны в Matrix client. - -### Claude's Discretion -- Точное место вызова reconciliation в startup flow -- Внутренняя структура helper-модуля (`bootstrap.py`, `reconcile.py` или аналог) -- Формат dev reset script и уровень автоматизации server-side cleanup -- Детали debug-logging и dry-run режима, если они помогают без раздувания scope - -### Deferred Ideas (OUT OF SCOPE) -- Full production-grade migration of historical Matrix state across schema versions -- Automatic server-side deletion/leave for all Matrix rooms and Space during reset, if it requires broader admin semantics -- Any Phase 2 SDK integration work - - -## Summary - -Phase 01.1 should be planned as a bootstrap/recovery phase, not as another chat-feature phase. The current Matrix adapter has no startup reconciliation path: `adapter/matrix/bot.py` logs in and goes directly to `sync_forever()`, while routing and command handlers assume `matrix_room:*`, `matrix_user:*`, and `chat:*` keys already exist. That means local DB loss currently produces logical corruption, not just missing cache. - -The safe standard approach is: perform a first sync that hydrates joined-room state, inspect the bot's current joined rooms and room state from the homeserver, rebuild the minimal local metadata needed for command routing, and only then enter the long-running sync loop. Reconciliation should be non-destructive and idempotent: if local keys already exist and match server state, leave them alone; if they are missing, recreate them; if they conflict, prefer the server room topology for Matrix-specific metadata and recreate missing `ChatManager` rows from that. - -For reset, separate two workflows explicitly. `local-only` reset is the default and should be automated. Optional server-side cleanup may leave/forget rooms for the bot account, but it cannot promise global deletion of Matrix rooms for all members; if that is not automated, the tool must print the exact manual steps for the Matrix client. - -**Primary recommendation:** Add a startup `reconcile_matrix_state()` step before `sync_forever()`, and ship a dev-only reset CLI with `local-only`, `server-leave-forget`, and `dry-run` modes. - -## Project Constraints (from CLAUDE.md) - -- Do not treat missing Lambda SDK as a blocker. -- Keep all platform calls behind `platform/interface.py`. -- Current runtime implementation is `platform/mock.py`; recommendations must work with that. -- Prefer architecture changes in adapters and core without coupling to future SDK internals. -- Use pytest-based verification. -- Do not recommend committing `.env`. -- Respect dependency order: `core/` first, then `platform/`, then adapters. - -## Standard Stack - -### Core -| Library | Version | Purpose | Why Standard | -|---------|---------|---------|--------------| -| Python | 3.14.3 installed | Runtime for bot and scripts | Already available locally; codebase targets `>=3.11`. | -| `matrix-nio` | 0.25.2, published 2024-10-04 | Matrix client, sync, room membership/state APIs | Already installed; exposes the exact bootstrap/reset APIs this phase needs. | -| `SQLiteStore` (repo) | local | Adapter/core KV persistence | Existing persistence contract for `matrix_user:*`, `matrix_room:*`, and `chat:*`. | -| Matrix Client-Server API | spec latest | Authoritative room membership/state semantics | Needed to reason about restart recovery and leave/forget behavior correctly. | - -### Supporting -| Library | Version | Purpose | When to Use | -|---------|---------|---------|-------------| -| `pytest` | 9.0.2, published 2025-12-06 | Test runner | For targeted adapter/bootstrap regression tests. | -| `pytest-asyncio` | 1.3.0, published 2025-11-10 | Async test execution | For async reconciliation/reset flows. | -| `structlog` | 25.5.0, published 2025-10-27 | Diagnostics | For reconciliation summaries and conflict logging. | -| `python-dotenv` | 1.2.2, published 2026-03-01 | Env loading | Already used by `adapter/matrix/bot.py` for Matrix config. | - -### Alternatives Considered -| Instead of | Could Use | Tradeoff | -|------------|-----------|----------| -| Startup reconciliation from joined rooms + state | Force developers to wipe local DB and recreate rooms | Simpler code, but directly violates D-01, D-02, D-05. | -| Non-destructive local rebuild | Full auto-recreate of Space/rooms on missing local state | Easier to implement, but causes duplicate Matrix rooms and breaks D-04. | -| Dev reset script | README-only manual ritual | Lower code cost, but not repeatable and fails D-08..D-10. | - -**Installation:** -```bash -uv sync -``` - -**Version verification:** Verified via installed environment and PyPI metadata on 2026-04-03: -- `matrix-nio` `0.25.2` - 2024-10-04 -- `pytest` `9.0.2` - 2025-12-06 -- `pytest-asyncio` `1.3.0` - 2025-11-10 -- `structlog` `25.5.0` - 2025-10-27 -- `python-dotenv` `1.2.2` - 2026-03-01 - -## Architecture Patterns - -### Recommended Project Structure -```text -adapter/matrix/ -├── bot.py # startup flow calls reconciliation before sync loop -├── reconcile.py # bootstrap/rebuild logic from Matrix server state -├── reset.py # dev-only reset CLI / entrypoint -├── room_router.py # room_id -> chat_id with recovery hook -├── store.py # metadata helpers, prefix scans, derived counters -└── handlers/ - ├── auth.py # first-time provisioning only - └── chat.py # uses recovered state, no provisioning fallback -``` - -### Pattern 1: Two-Phase Startup Bootstrap -**What:** Split startup into `login -> initial sync/full_state -> reconcile -> steady-state sync_forever`. -**When to use:** Always for Matrix bot startup when local DB may be missing or stale. -**Example:** -```python -# Source: matrix-nio AsyncClient docs/source + repo startup flow -client = AsyncClient(...) -runtime = build_runtime(store=SQLiteStore(db_path), client=client) - -await login_or_restore_session(client) -await client.sync(timeout=0, full_state=True) -report = await reconcile_matrix_state(client, runtime.store, runtime.chat_mgr) -logger.info("matrix_reconcile_complete", **report) -await client.sync_forever(timeout=30000) -``` - -### Pattern 2: Rebuild Local Metadata From Joined Rooms -**What:** Enumerate joined rooms, inspect local hydrated room objects or room state, and recreate missing `matrix_room:*`, `matrix_user:*`, and `chat:*` records. -**When to use:** On startup and optionally on `unregistered:{room_id}` fallback at runtime. -**Example:** -```python -# Source: matrix-nio AsyncClient.joined_rooms/room_get_state + repo store contracts -joined = await client.joined_rooms() -for room_id in joined.rooms: - state = await client.room_get_state(room_id) - # detect: space room vs chat room, owner user, child relationship, display name - # rebuild matrix_room:{room_id} - # rebuild chat:{matrix_user_id}:{chat_id} if absent -``` - -### Pattern 3: Non-Destructive Reconciliation Report -**What:** Return a structured report: scanned rooms, restored rooms, restored chats, conflicts, skipped rooms. -**When to use:** Every reconciliation run, including dry-run. -**Example:** -```python -{ - "joined_rooms": 4, - "restored_user_meta": 1, - "restored_room_meta": 3, - "restored_chat_rows": 3, - "conflicts": [], - "skipped_rooms": ["!dm:example.org"], -} -``` - -### Pattern 4: Reset Modes Are Explicit -**What:** Separate `local-only`, `server-leave-forget`, and `dry-run`. -**When to use:** For dev/QA only. Never mix destructive server cleanup into normal startup. -**Example:** -```bash -uv run python -m adapter.matrix.reset --mode local-only -uv run python -m adapter.matrix.reset --mode server-leave-forget --dry-run -``` - -### Anti-Patterns to Avoid -- **Provisioning during reconciliation:** Do not create a new Space or new rooms while trying to recover missing local state. -- **Treating `next_chat_index` as primary truth:** Derive it from recovered `chat_id` values after scan; do not trust a missing or stale counter. -- **Routing unknown rooms straight through:** `unregistered:{room_id}` is a signal to reconcile, not a stable runtime identity. -- **Destructive reset by default:** Startup must never leave/forget rooms automatically. -- **Blindly trusting local `surface_ref`:** If `chat:*` and `matrix_room:*` disagree, rebuild from Matrix room metadata and repair the chat row. - -## Don't Hand-Roll - -| Problem | Don't Build | Use Instead | Why | -|---------|-------------|-------------|-----| -| Room discovery | Custom DB-only reconstruction heuristics | `AsyncClient.joined_rooms()` plus synced room state | Server already knows which rooms the bot joined. | -| Space membership detection | Naming-convention parsing of room names | Matrix state: `m.room.create.type`, `m.space.child`, `m.space.parent` | Names are mutable and non-authoritative. | -| Room cleanup semantics | Custom “delete room” assumptions | `room_leave()` + `room_forget()` semantics | Client API supports leave/forget, not guaranteed global deletion. | -| Chat ID recovery | Hardcoded `C1/C2/...` reset | Rebuild from existing `matrix_room:*`/server state and compute next index | Prevents collisions after partial DB loss. | -| Diagnostic output | Ad hoc `print()` strings | Structured reconciliation/reset report via `structlog` | Easier manual QA and failure triage. | - -**Key insight:** The homeserver already persists the bot’s room graph. This phase should rehydrate local cache from that graph, not attempt to replace it with a second custom truth model. - -## Common Pitfalls - -### Pitfall 1: Joining the sync loop before reconciliation -**What goes wrong:** Commands arrive while local metadata is still missing, producing `unregistered:{room_id}` routing or `ChatManager` misses. -**Why it happens:** Current `main()` enters `sync_forever()` immediately after login. -**How to avoid:** Perform initial sync and reconciliation first. -**Warning signs:** `unregistered_room` logs immediately after restart; `ValueError("Chat ... not found")` on `!rename` or `!archive`. - -### Pitfall 2: Recovering room metadata but not chat rows -**What goes wrong:** Room routing works, but `ChatManager.rename/archive/list_active` still fails because `chat:{user}:{chat_id}` rows were not recreated. -**Why it happens:** Matrix adapter metadata and core chat metadata live in different keyspaces. -**How to avoid:** Reconciliation must repair both stores in one pass. -**Warning signs:** `matrix_room:*` exists but `chat:*` keys do not. - -### Pitfall 3: Trusting stale `next_chat_index` -**What goes wrong:** New chats reuse existing `C` IDs after local recovery. -**Why it happens:** `next_chat_id()` increments a persisted counter that may be absent or behind. -**How to avoid:** After scan, set `next_chat_index = max(recovered_chat_numbers) + 1`. -**Warning signs:** New room gets `C1` even though Space already contains prior rooms. - -### Pitfall 4: Assuming room names identify chat rooms safely -**What goes wrong:** Reconciliation binds the wrong room because a user renamed a room or Space. -**Why it happens:** Names are user-facing labels, not stable identifiers. -**How to avoid:** Prefer room state and existing `chat_id` metadata; use display names only as fallback. -**Warning signs:** Duplicate “Чат 1” names or renamed rooms break matching. - -### Pitfall 5: Over-promising full cleanup -**What goes wrong:** Reset script claims a “clean slate” but rooms still exist in Element or for other members. -**Why it happens:** Leaving/forgetting affects the bot account’s membership/history, not necessarily global room deletion. -**How to avoid:** Name the mode accurately and print the manual client steps when needed. -**Warning signs:** QA reruns still show old rooms in the user’s client. - -## Code Examples - -Verified patterns from official sources and the installed library surface: - -### Initial Sync Before Reconcile -```python -# Source: matrix-nio AsyncClient.sync/sync_forever -await client.sync(timeout=0, full_state=True) -report = await reconcile_matrix_state(client, store, chat_mgr) -await client.sync_forever(timeout=30000) -``` - -### Space Child Link Creation -```python -# Source: Matrix client-server API state event + current auth/new-chat flow -await client.room_put_state( - room_id=space_id, - event_type="m.space.child", - content={"via": [homeserver]}, - state_key=chat_room_id, -) -``` - -### Bot-Side Leave/Forget Cleanup -```python -# Source: matrix-nio AsyncClient.room_leave / room_forget -for room_id in room_ids: - await client.room_leave(room_id) - await client.room_forget(room_id) -``` - -### Router Recovery Trigger -```python -# Source: repo room_router contract -chat_id = await resolve_chat_id(store, room_id, matrix_user_id) -if chat_id.startswith("unregistered:"): - await reconcile_single_room(client, store, chat_mgr, room_id, matrix_user_id) -``` - -## State of the Art - -| Old Approach | Current Approach | When Changed | Impact | -|--------------|------------------|--------------|--------| -| Local adapter DB treated as the operational truth | Rebuildable local cache from server room graph | Mature Matrix client practice; supported by current Matrix CS API and `matrix-nio` | Restart no longer requires destructive local reset. | -| Manual room cleanup in client after experiments | Scripted leave/forget plus explicit manual instructions | Current `matrix-nio` 0.25.x API surface | QA becomes repeatable and auditable. | -| Immediate steady-state sync after login | Initial sync/full-state bootstrap before long polling | Supported by current `AsyncClient.sync()` / `sync_forever()` behavior | Reconciliation can run before any user traffic is handled. | - -**Deprecated/outdated:** -- `README.md` Matrix manual QA instruction `rm -f lambda_matrix.db` as the primary restart flow: outdated for this phase. -- DM-first Matrix recovery assumptions in `docs/matrix-prototype.md`: outdated relative to Phase 1 Space+rooms decisions. - -## Open Questions - -1. **How exactly should reconciliation identify the owning Matrix user for a recovered room when local `matrix_room:*` is gone?** - - What we know: the bot can enumerate joined rooms and fetch room state; current healthy metadata stores `matrix_user_id` and `space_id`. - - What's unclear: whether Phase 1-created rooms also expose enough server-side structure to recover owner deterministically without existing local metadata in every case. - - Recommendation: Plan a proof test against a real homeserver/client. If room-state-only ownership is ambiguous, persist a tiny bot-authored marker state event going forward, but keep that addition narrowly scoped. - -2. **Should runtime recovery happen only on startup, or also lazily on first unknown room access?** - - What we know: startup repair satisfies D-02/D-07 for common restart loss; `room_router` already surfaces unknown rooms cleanly. - - What's unclear: whether partial DB corruption during runtime is common enough to justify lazy single-room repair in Phase 01.1. - - Recommendation: Make startup reconciliation required, lazy room repair optional if it stays small. - -3. **How much of server cleanup should Phase 01.1 automate?** - - What we know: `room_leave()` and `room_forget()` are available; global room deletion is not what the client API guarantees. - - What's unclear: whether automating bot-side leave/forget is worth the extra risk for this urgent phase. - - Recommendation: Keep `local-only` mandatory. Make server cleanup optional and clearly labeled experimental/dev-only if included. - -## Environment Availability - -| Dependency | Required By | Available | Version | Fallback | -|------------|------------|-----------|---------|----------| -| Python | Runtime, scripts, tests | ✓ | 3.14.3 | — | -| `uv` | Standard install/run workflow | ✓ | 0.9.30 | `python -m` + existing venv | -| `pytest` | Automated verification | ✓ | 9.0.2 | `uv run pytest` | -| Matrix homeserver credentials | Real restart/reset manual QA | ✗ in current shell | — | Manual-only after `.env` is configured | -| Matrix bot local DB/store paths | Reset workflow | ✓ | defaults in code | Can override with `MATRIX_DB_PATH` / `MATRIX_STORE_PATH` | - -**Missing dependencies with no fallback:** -- Live Matrix credentials for real manual reconciliation/reset QA. - -**Missing dependencies with fallback:** -- None for repository-only implementation and tests. - -## Validation Architecture - -### Test Framework -| Property | Value | -|----------|-------| -| Framework | `pytest 9.0.2` + `pytest-asyncio 1.3.0` | -| Config file | `pyproject.toml` | -| Quick run command | `pytest tests/adapter/matrix -v` | -| Full suite command | `pytest tests/ -v` | - -### Phase Requirements → Test Map -| Req ID | Behavior | Test Type | Automated Command | File Exists? | -|--------|----------|-----------|-------------------|-------------| -| PH01.1-BOOT | Startup rebuilds missing `matrix_user:*`, `matrix_room:*`, and `chat:*` from existing rooms without creating new rooms | unit/integration | `pytest tests/adapter/matrix/test_reconcile.py -v` | ❌ Wave 0 | -| PH01.1-ROUTER | Unknown room fallback can trigger repair or yields diagnosable warning without crashing commands | unit | `pytest tests/adapter/matrix/test_room_router_reconcile.py -v` | ❌ Wave 0 | -| PH01.1-COUNTER | Reconciliation resets `next_chat_index` to recovered max + 1 | unit | `pytest tests/adapter/matrix/test_reconcile.py -k next_chat_index -v` | ❌ Wave 0 | -| PH01.1-RESET | Dev reset `local-only` removes local DB/store paths and prints next steps | unit/smoke | `pytest tests/adapter/matrix/test_reset.py -v` | ❌ Wave 0 | -| PH01.1-NONDESTRUCTIVE | Reconciliation never calls room creation APIs | unit | `pytest tests/adapter/matrix/test_reconcile.py -k no_create -v` | ❌ Wave 0 | - -### Sampling Rate -- **Per task commit:** `pytest tests/adapter/matrix -v` -- **Per wave merge:** `pytest tests/ -v` -- **Phase gate:** Full suite green before `/gsd:verify-work` - -### Wave 0 Gaps -- [ ] `tests/adapter/matrix/test_reconcile.py` - startup reconciliation scenarios -- [ ] `tests/adapter/matrix/test_reset.py` - CLI/script reset modes and output -- [ ] `tests/adapter/matrix/test_room_router_reconcile.py` - lazy recovery or warning behavior -- [ ] Integration fixture for a fake `AsyncClient` response surface matching `joined_rooms()` and `room_get_state()` - -## Sources - -### Primary (HIGH confidence) -- Matrix Client-Server API - room state, leave, forget, joined rooms, Spaces semantics: https://spec.matrix.org/latest/client-server-api/index.html -- `matrix-nio` installed 0.25.2 API surface verified locally on 2026-04-03 via `AsyncClient.sync`, `sync_forever`, `joined_rooms`, `room_get_state`, `room_leave`, `room_forget` -- Repo code: [adapter/matrix/bot.py](/Users/a/MAI/sem2/lambda/surfaces-bot/adapter/matrix/bot.py), [adapter/matrix/store.py](/Users/a/MAI/sem2/lambda/surfaces-bot/adapter/matrix/store.py), [adapter/matrix/room_router.py](/Users/a/MAI/sem2/lambda/surfaces-bot/adapter/matrix/room_router.py), [adapter/matrix/handlers/auth.py](/Users/a/MAI/sem2/lambda/surfaces-bot/adapter/matrix/handlers/auth.py), [core/chat.py](/Users/a/MAI/sem2/lambda/surfaces-bot/core/chat.py) -- PyPI release metadata: https://pypi.org/project/matrix-nio/ , https://pypi.org/project/pytest/ , https://pypi.org/project/pytest-asyncio/ , https://pypi.org/project/structlog/ , https://pypi.org/project/python-dotenv/ - -### Secondary (MEDIUM confidence) -- [README.md](/Users/a/MAI/sem2/lambda/surfaces-bot/README.md) - current manual reset habit and run commands -- [docs/matrix-prototype.md](/Users/a/MAI/sem2/lambda/surfaces-bot/docs/matrix-prototype.md) - original Matrix UX intent, noting outdated DM/reaction sections -- [01-CONTEXT.md](/Users/a/MAI/sem2/lambda/surfaces-bot/.planning/phases/01-matrix-qa-polish/01-CONTEXT.md) - locked Phase 1 Matrix decisions -- [01-VERIFICATION.md](/Users/a/MAI/sem2/lambda/surfaces-bot/.planning/phases/01-matrix-qa-polish/01-VERIFICATION.md) - what has already been verified and what still needs human Matrix QA - -### Tertiary (LOW confidence) -- None - -## Metadata - -**Confidence breakdown:** -- Standard stack: HIGH - verified against installed environment, PyPI metadata, and official Matrix spec -- Architecture: HIGH - directly grounded in current repo flow plus current `matrix-nio`/Matrix capabilities -- Pitfalls: HIGH - derived from concrete gaps in current startup/store/router code - -**Research date:** 2026-04-03 -**Valid until:** 2026-05-03 diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-VALIDATION.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-VALIDATION.md deleted file mode 100644 index 336cbd6..0000000 --- a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-VALIDATION.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -phase: 01.1 -slug: matrix-restart-reconciliation-and-dev-reset-workflow -status: draft -nyquist_compliant: false -wave_0_complete: false -created: 2026-04-03 ---- - -# Phase 01.1 — Validation Strategy - -> Per-phase validation contract for feedback sampling during execution. - ---- - -## Test Infrastructure - -| Property | Value | -|----------|-------| -| **Framework** | `pytest 9.0.2` + `pytest-asyncio 1.3.0` | -| **Config file** | `pyproject.toml` | -| **Quick run command** | `pytest tests/adapter/matrix -v` | -| **Full suite command** | `pytest tests/ -v` | -| **Estimated runtime** | ~20 seconds | - ---- - -## Sampling Rate - -- **After every task commit:** Run `pytest tests/adapter/matrix -v` -- **After every plan wave:** Run `pytest tests/ -v` -- **Before `$gsd-verify-work`:** Full suite must be green -- **Max feedback latency:** 20 seconds - ---- - -## Per-Task Verification Map - -| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | -|---------|------|------|-------------|-----------|-------------------|-------------|--------| -| 01.1-01-01 | 01 | 1 | PH01.1-BOOT | unit/integration | `pytest tests/adapter/matrix/test_reconcile.py -v` | ❌ W0 | ⬜ pending | -| 01.1-01-01 | 01 | 1 | PH01.1-COUNTER | unit | `pytest tests/adapter/matrix/test_reconcile.py -k next_chat_index -v` | ❌ W0 | ⬜ pending | -| 01.1-01-01 | 01 | 1 | PH01.1-NONDESTRUCTIVE | unit | `pytest tests/adapter/matrix/test_reconcile.py -k no_create -v` | ❌ W0 | ⬜ pending | -| 01.1-02-01 | 02 | 2 | PH01.1-BOOT | unit | `pytest tests/adapter/matrix/test_dispatcher.py -k startup -v` | ✅ | ⬜ pending | -| 01.1-02-02 | 02 | 2 | PH01.1-ROUTER | unit | `pytest tests/adapter/matrix/test_dispatcher.py -k reconcile -v` | ✅ | ⬜ pending | -| 01.1-03-01 | 03 | 1 | PH01.1-RESET | unit/smoke | `pytest tests/adapter/matrix/test_reset.py -v` | ❌ W0 | ⬜ pending | -| 01.1-03-02 | 03 | 1 | PH01.1-RESET | smoke | `python -m adapter.matrix.reset --help` | ❌ W0 | ⬜ pending | - -*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* - ---- - -## Wave 0 Requirements - -- [ ] `tests/adapter/matrix/test_reconcile.py` — startup reconciliation scenarios, `next_chat_index`, and no-provisioning assertions -- [ ] `tests/adapter/matrix/test_reset.py` — CLI reset modes, dry-run behavior, and operator guidance output -- [ ] `tests/adapter/matrix/test_dispatcher.py` — startup bootstrap order and targeted unknown-room recovery coverage -- [ ] Fake `AsyncClient` fixture surface for joined rooms, room state, leave, and forget behavior - ---- - -## Manual-Only Verifications - -| Behavior | Requirement | Why Manual | Test Instructions | -|----------|-------------|------------|-------------------| -| Reconciled Space/chat rooms render correctly in a real Matrix client after restart | PH01.1-BOOT | Client UX and homeserver state cannot be fully trusted from fake nio fixtures | 1. Start the bot with existing Space/chat rooms. 2. Verify the bot does not create duplicate Space or chat rooms. 3. Send a command in a recovered room and confirm it routes normally. | -| Server-side cleanup leaves the account in a usable Element state after `server-leave-forget` | PH01.1-RESET | Element/archive behavior and homeserver retention are client/server integration concerns | 1. Run `python -m adapter.matrix.reset --mode server-leave-forget --dry-run`. 2. Run without `--dry-run` on a test account. 3. Confirm joined rooms disappear for the bot and fresh invites can be accepted cleanly. | - ---- - -## Validation Sign-Off - -- [ ] All tasks have `` verify or Wave 0 dependencies -- [ ] Sampling continuity: no 3 consecutive tasks without automated verify -- [ ] Wave 0 covers all MISSING references -- [ ] No watch-mode flags -- [ ] Feedback latency < 20s -- [ ] `nyquist_compliant: true` set in frontmatter - -**Approval:** pending diff --git a/.planning/phases/02-prototype/.continue-here.md b/.planning/phases/02-prototype/.continue-here.md deleted file mode 100644 index a2d4619..0000000 --- a/.planning/phases/02-prototype/.continue-here.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -phase: 02-prototype -task: 4 -total_tasks: 4 -status: paused -last_updated: 2026-04-07T23:54:30.473Z ---- - - -The Matrix direct-agent prototype is implemented and manually proven working on branch `feat/matrix-direct-agent-prototype`. The current code path can log into Matrix, accept invites, provision the first Space/chat tree for a fresh user, and send live text messages to a patched local `platform-agent` over WebSocket. The immediate remaining engineering gap is not feature delivery but resilience: backend/provider failures can still bubble up as `PlatformError` and crash the Matrix bot process. - - - - -- Task 1: Added `sdk/agent_session.py` and transport tests for direct WebSocket messaging with collision-safe `thread_key` generation. -- Task 2: Added `sdk/prototype_state.py` and tests for stable local user mapping, settings defaults, and mutation-safe settings copies. -- Task 3: Added `sdk/real.py` as the `PlatformClient` implementation, fixed import-time dependency leakage, and aligned thread-key tests to the actual dispatcher contract. -- Task 4: Wired Matrix runtime selection through `MATRIX_PLATFORM_BACKEND=real`, documented usage in `README.md`, and added dispatcher coverage for real backend selection. -- Fixed repeat Matrix invites so the bot now `join()`s before the existing-user early return path. -- Added Russian runbook doc `docs/matrix-direct-agent-prototype-ru.md` and pushed the branch. -- Manually validated live bring-up using a local patched `external/platform-agent` on port 8000 plus the Matrix homeserver `https://matrix.lambda.coredump.ru`. - - - - -- Add graceful degradation for backend/provider failures so `PlatformError` does not crash the Matrix process. -- Decide whether to upstream or separately push the required `external/platform-agent` patch (`1dca2c1`) that enables WebSocket `thread_id`. -- Optionally clean up repeat-invite UX if Space/chat reprovisioning should ever happen for already-known users. -- Optionally prepare a PR from `feat/matrix-direct-agent-prototype`. - - - - -- Keep the prototype in this repo, not a separate Matrix-only repo. -- Keep Matrix adapter logic intact and absorb backend differences inside `sdk/`. -- Split the real backend into `AgentSessionClient` and `PrototypeStateStore` behind `RealPlatformClient`. -- Patch only `platform-agent` for per-thread memory instead of changing both `agent` and `agent_api`. -- Use a serialized collision-safe thread key because Matrix user IDs contain colons. -- For repeat invites, join the room but do not recreate Space/chat state if the user is already provisioned locally. - - - -- Technical: provider/backend errors still crash the Matrix bot instead of returning a user-facing failure reply. -- External: the required `platform-agent` patch exists only in the local clone under `external/` and is not yet upstream. -- Operational: credentials used during manual bring-up were exposed in-session and should be rotated. - - - -The important mental model is stable. `platform/master` is still not the backend for surfaces, so the working prototype goes directly to `platform-agent` over `/agent_ws/`. The live setup that worked was: -- `surfaces-bot` branch: `feat/matrix-direct-agent-prototype` -- Matrix bot env: `MATRIX_PLATFORM_BACKEND=real`, `AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/` -- patched local `external/platform-agent` with `thread_id` support -- provider configured through OpenRouter using model `qwen/qwen3.5-122b-a10b` - -Important files: -- `sdk/agent_session.py` -- `sdk/prototype_state.py` -- `sdk/real.py` -- `adapter/matrix/bot.py` -- `adapter/matrix/handlers/auth.py` -- `docs/matrix-direct-agent-prototype-ru.md` - -Important local-only dependency: -- `external/platform-agent` commit `1dca2c1` (`feat: support websocket thread ids`) - -Likely running background process at pause time: -- local `platform-agent` server on port 8000, PID 13499 - - - -Start with the failure path: catch `PlatformError` around Matrix message handling so a bad provider response becomes a normal reply like “backend unavailable, try again later” instead of killing the process. After that, either upstream `external/platform-agent` commit `1dca2c1` or document it as an explicit prerequisite in the platform repo. - From 3340c126d619345e7bcf2a2ee3213c9f531e57ac Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 23:42:34 +0300 Subject: [PATCH 55/55] docs: remove legacy threads and reports from planning state --- .planning/.continue-here.md | 72 ---------- .planning/reports/20260422-session-report.md | 92 ------------ ...trix-dev-prototype-agent-platform-state.md | 133 ------------------ .../threads/matrix-file-ingestion-context.md | 81 ----------- 4 files changed, 378 deletions(-) delete mode 100644 .planning/.continue-here.md delete mode 100644 .planning/reports/20260422-session-report.md delete mode 100644 .planning/threads/matrix-dev-prototype-agent-platform-state.md delete mode 100644 .planning/threads/matrix-file-ingestion-context.md diff --git a/.planning/.continue-here.md b/.planning/.continue-here.md deleted file mode 100644 index f27ae84..0000000 --- a/.planning/.continue-here.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -context: pre-planning -phase: 05-deployment -task: 0 -total_tasks: 0 -status: ready-to-plan -last_updated: 2026-04-27T18:44:51.832Z ---- - - -Phase 04 полностью завершена и закоммичена на ветке `feat/matrix-direct-agent-prototype` (135 тестов зелёные). Этот сеанс был посвящён архитектуре деплоя — изучили платформенные репозитории и обсудили топологию с командой платформы. Вся информация о деплое зафиксирована в `docs/deploy-architecture.md`. Phase 05 не спланирована, следующий шаг — `/gsd-plan-phase`. - - - - -- Изучены актуальные версии platform-agent, platform-agent_api, platform-master -- Уточнена топология деплоя с платформой (схема с reverse proxy и shared volume) -- Созданы `docs/deploy-architecture.md` — полное summary архитектуры деплоя - - - - -- Смержить `feat/matrix-direct-agent-prototype` → `main` -- Спланировать Phase 05 (деплой) -- Выполнить Phase 05: - - Обновить `config/matrix-agents.yaml` (добавить `base_url`, `workspace_path`, `user_agents`) - - Обновить `sdk/real.py` (AgentApi конструктор, file transfer) - - Обработка `MsgEventSendFile` в Matrix адаптере (скачать файл из volume, отправить пользователю) - - Обработка входящих файлов от Matrix пользователей (сохранить в workspace, передать в attachments) - - Написать `docker-compose.yml` для деплоя - - - - -- **Топология**: один инстанс Matrix-бота, один агент-контейнер на пользователя, reverse proxy на `lambda.coredump.ru:7000` роутит по пути `/agent_N/` -- **Файлы**: через shared volume `/agents/`. Surface пишет файл в `/agents/{N}/`, передаёт относительный путь в `attachments=["file.txt"]`. При `MsgEventSendFile(path)` — читает файл из `/agents/{N}/{path}` и шлёт в Matrix. -- **Agent API**: используем master (`attachments` и `MsgEventSendFile` есть). Ветку `#9-clientside-tool-call` игнорируем — она в разработке и убирает нужные фичи. -- **Конфиг**: два словаря — `user_id → agent_id` и `agent_id → {base_url, workspace_path}` -- **Master**: не используем для MVP. Статический конфиг. При готовности Master — мигрируем. -- **chat_id**: пока `chat_id=0` (один контекст на пользователя) - - - - -- **AGENT_ID + COMPOSIO_API_KEY**: Composio смержен в main platform-agent, теперь обязателен. Значения нужны от Азамата перед деплоем. -- **agent_api #9**: убирает `attachments` и `MsgEventSendFile` — если смержат до деплоя, сломает наш file transfer. Нужно уточнить сроки. - - -## Required Reading (in order) - -1. `docs/deploy-architecture.md` — полная архитектура деплоя, топология, API, файловый обмен, конфиг -2. `adapter/matrix/routed_platform.py` — текущий RoutedPlatformClient -3. `sdk/real.py` — текущий AgentApi wrapper -4. `config/matrix-agents.yaml` и `config/matrix-agents.example.yaml` — текущий формат конфига (нужно расширить) - -## Infrastructure State - -- Ветка: `feat/matrix-direct-agent-prototype` — готова к merge, 135 тестов зелёные -- `config/matrix-agents.yaml` — незакоммичен (live config, добавить в `.gitignore`) -- `docs/deploy-architecture.md` — незакоммичен (новый файл этого сеанса) -- platform-agent main: Composio уже смержен (требует `AGENT_ID`, `COMPOSIO_API_KEY` в env) - - -Архитектура деплоя полностью прояснена. Нет неизвестных блокеров (кроме env-переменных от платформы). Phase 05 — чисто инженерная задача: обновить конфиг, sdk, Matrix адаптер, написать compose. Всё что нужно знать — в docs/deploy-architecture.md. - - - -1. /clear -2. /gsd-resume-work — прочитает этот файл и предложит план Phase 05 -3. Прочитать docs/deploy-architecture.md -4. /gsd-plan-phase 05 - diff --git a/.planning/reports/20260422-session-report.md b/.planning/reports/20260422-session-report.md deleted file mode 100644 index 9044d2b..0000000 --- a/.planning/reports/20260422-session-report.md +++ /dev/null @@ -1,92 +0,0 @@ -# GSD Session Report - -**Generated:** 2026-04-21T22:33:11.666Z -**Project:** surfaces-bot -**Milestone:** v1.0 — Production-ready surfaces - ---- - -## Session Summary - -**Duration:** Single session -**Phase Progress:** Phase 04 implemented; current follow-up work is audit, stabilization, and platform bug localization -**Plans Executed:** 0 formal GSD plans executed in this session; work was focused on post-implementation audit and cleanup -**Commits Made:** 6 - -## Work Performed - -### Phases Touched - -- **Phase 04** — Matrix MVP follow-up after implementation: - - completed audit of platform patches vs surface-owned responsibilities - - removed dependence on local platform modifications for `chat_id` - - switched Matrix integration to numeric `platform_chat_id` mapping on our side - - cleaned transport layer to a thin adapter over upstream `AgentApi` - - updated README and run instructions - - produced final Russian bug report with raw-trace-based diagnosis - -### Key Outcomes - -- Platform repos are clean and synced to pinned upstream commits. -- Matrix real backend works with numeric surrogate `platform_chat_id`. -- `surfaces` transport layer no longer owns custom stream semantics. -- Final diagnosis was narrowed: missing-first-chunk bug is now considered platform-side with direct raw evidence. -- Working state was committed and pushed on `feat/matrix-direct-agent-prototype`. - -### Decisions Made - -- Do not patch vendored platform repos for the working implementation. -- Keep `surfaces` transport layer thin and upstream-aligned. -- Treat the current streaming bug as platform-side unless new evidence disproves it. -- Do not add new local stream workarounds that would blur responsibility. - -## Files Changed - -- `README.md` -- `adapter/matrix/bot.py` -- `sdk/agent_api_wrapper.py` -- `sdk/real.py` -- `tests/platform/test_real.py` -- `tests/adapter/matrix/test_dispatcher.py` -- `tests/core/test_integration.py` -- `docs/reports/2026-04-22-platform-streaming-final-bug-report-ru.md` - -Planning / handoff artifacts updated: - -- `.planning/HANDOFF.json` -- `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/.continue-here.md` -- `.planning/reports/20260422-session-report.md` - -## Blockers & Open Items - -- Platform-side streaming bug after tool/file flow. -- Duplicate `END` from platform. -- Image path failure on oversized `data:` URI. -- `tokens_used` remains unavailable from pinned upstream client. - -## Estimated Resource Usage - -| Metric | Estimate | -|--------|----------| -| Commits | 6 | -| Files changed | 8 code/docs files in the main deliverable, plus planning artifacts | -| Plans executed | 0 formal plans in this session | -| Subagents spawned | 0 | - -> **Note:** Token and cost estimates require API-level instrumentation. -> These metrics reflect observable session activity only. - ---- - -### Recent Commits - -- `0c2884c` — `refactor: use thin upstream transport adapter` -- `569824e` — `refactor: shrink agent api wrapper to thin adapter` -- `4d917ac` — `docs: add thin transport adapter plan` -- `3a3fcdc` — `docs: add thin transport adapter design` -- `7a2ad86` — `docs: clarify matrix file sending flow` -- `4524a6a` — `feat: finalize matrix platform audit and docs` - ---- - -*Generated by `$gsd-session-report`* diff --git a/.planning/threads/matrix-dev-prototype-agent-platform-state.md b/.planning/threads/matrix-dev-prototype-agent-platform-state.md deleted file mode 100644 index facd575..0000000 --- a/.planning/threads/matrix-dev-prototype-agent-platform-state.md +++ /dev/null @@ -1,133 +0,0 @@ -# Thread: Matrix dev prototype — состояние агента и платформы - -## Status: IN PROGRESS - -## Goal - -Зафиксировать текущее состояние платформы для последующей разработки Matrix dev прототипа, -в котором команды разработки скиллов смогут быстро добавлять и обкатывать скиллы. - -## Context - -*Исследование проведено 2026-04-14. Репозитории: `external/platform-agent`, `external/platform-agent_api`, `external/platform-master`.* - -### Решение по деплою: локальный контейнер у каждого разработчика - -`platform-master` не готов для общего деплоя: -- lifecycle management контейнеров (TTL, cleanup, переиспользование сессий) — в ветке `feat/storage`, не смержено в main -- без него при общем деплое контейнеры висят вечно, ресурсы не освобождаются - -Локальный вариант: `make up-dev` — полностью рабочий, volume mount `./workspace:/workspace/`, hot reload src. - -### Архитектура изоляции контекстов - -`AgentService` — singleton с `thread_id = "default"` — это **намеренно**. Архитектура Master предполагает один контейнер `platform-agent` на один чат. Изоляция на уровне контейнеров, не thread_id. Фиксить не нужно. - -### Система скиллов (deepagents) - -`SkillsMiddleware` в `deepagents` полностью готов: -- скилл = директория с `SKILL.md` (YAML frontmatter + markdown инструкции) -- progressive disclosure: агент видит имя+описание в system prompt, читает полный файл по требованию -- загружается один раз при старте сессии, кэшируется в LangGraph state - -**НЕ подключено** в `platform-agent/src/agent/base.py` — отсутствует одна строка: -```python -skills=["/workspace/skills/"] -``` -Это задача для команды платформы. - -### Workflow разработчика скилла - -``` -workspace/ - skills/ - my-skill/ - SKILL.md ← редактируешь здесь (live через volume mount) - helper.py ← вспомогательные файлы - config/ - my-skill.json ← токены и настройки (пишет агент при первом запуске) -``` - -1. Редактируешь `SKILL.md` -2. `!new` в Matrix (новая сессия = скиллы перечитываются) -3. Проверяешь поведение -4. Повторяешь - -Агент может **сам установить скилл** из GitHub: -- `execute` → git clone -- `write_file` → положить в `/workspace/skills/` -- после `!new` скилл активен - -### Конфигурация скиллов (токены, API ключи) - -Агент управляет конфигом сам: -- первый запуск: спрашивает пользователя → пишет в `/workspace/config/skill-name.json` -- последующие запуски: читает из файла -- файл персистентен между сессиями (volume mount) - -### Входящий протокол (что принимает агент) - -`ClientMessage` — только `text: str`. Файлы и изображения не поддерживаются. -Задача для платформы — расширить протокол. - -### Исходящий протокол (что шлёт агент) - -Новые события с `origin/main` (апрель 2026): -- `AGENT_EVENT_TOOL_CALL_CHUNK` — агент вызывает инструмент -- `AGENT_EVENT_TOOL_RESULT` — результат инструмента -- `AGENT_EVENT_CUSTOM_UPDATE` — произвольный прогресс - -**Наш `sdk/agent_session.py` падает на этих событиях** (`raise PlatformError("Unexpected agent message")`). -Нужно починить — это наша задача, ~10 строк. - -### AgentApi из lambda_agent_api - -Готовый production-клиент с правильным lifecycle (`connect()`, `close()`, `send_message()` как `AsyncIterator`). -Наш `sdk/agent_session.py` дублирует его функциональность. Стоит заменить. - -### Инструменты агента из коробки - -- `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` — файловые операции в workspace -- `execute` — shell под изолированным OS-пользователем `agent` -- `write_todos` — список задач -- `task` — вызов субагентов - -### Запуск локально - -```bash -# .env минимально необходимый: -PROVIDER_URL=https://openrouter.ai/api/v1 -PROVIDER_API_KEY=<ключ> -PROVIDER_MODEL=anthropic/claude-sonnet-4-6 - -# Dev контейнер: -make up-dev # требует AGENT_API_PATH=../platform-agent_api в env -``` - -Dev Dockerfile монтирует `./workspace:/workspace/` и `./src:/app/src` (hot reload). - -## Что нужно от платформы - -1. Добавить `skills=["/workspace/skills/"]` в `platform-agent/src/agent/base.py` -2. Поддержка файлов/изображений в `ClientMessage` (не срочно для MVP) -3. Lifecycle management контейнеров в Master (для общего деплоя, не срочно) - -## Что делаем мы - -1. Починить `sdk/agent_session.py` — обработка tool-событий вместо исключения -2. (опционально) Заменить `AgentSessionClient` на `AgentApi` из `lambda_agent_api` - -## References - -- `external/platform-agent` — локальный клон, наш патч `1dca2c1` (thread_id) поверх `1e9fa1f` -- `external/platform-agent_api` — локальный клон, актуальный (origin/master = `bb20a84`) -- `external/platform-master` — локальный клон, активная разработка в `feat/storage-s02` -- `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md` -- `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md` - -## Next Steps - -1. Запросить у команды платформы: подключение `SkillsMiddleware` в `base.py` -2. Починить `sdk/agent_session.py` — обработать tool-события -3. Написать первый тестовый скилл (`workspace/skills/hello/SKILL.md`) и проверить end-to-end -4. Документировать workflow для разработчиков скиллов diff --git a/.planning/threads/matrix-file-ingestion-context.md b/.planning/threads/matrix-file-ingestion-context.md deleted file mode 100644 index 0ccb079..0000000 --- a/.planning/threads/matrix-file-ingestion-context.md +++ /dev/null @@ -1,81 +0,0 @@ -# Thread: Matrix file ingestion and agent-visible storage contract - -## Status: IN PROGRESS - -## Goal - -Сохранить текущий контекст сессии для следующего агента и зафиксировать следующую архитектурную развилку: как принимать вложения из Matrix и делать их доступными агенту. - -## Current State - -Phase 4 Matrix MVP уже собран и проверен на уровне per-room routing: -- обычные сообщения теперь идут в `platform_chat_id`, а не в общий локальный `C1/C2` -- `!context` показывает состояние текущего Matrix-чата -- `!save` и `!load` привязаны к текущему room-context -- `PrototypeStateStore` хранит live state per context -- последние изменения закоммичены в `feat/matrix-direct-agent-prototype` - -Коммиты, которые важно знать: -- `c11c8ec` `feat(task-5): scope matrix context state per room` -- `07c5078` `feat(task-7): verify matrix per-room context routing` - -## What We Learned About Platform Runtime - -Текущий `external/platform-agent` не является отдельным контейнером на чат. -Фактическая модель сейчас такая: -- один FastAPI-процесс -- singleton `AgentService` -- `thread_id` используется как ключ памяти в LangGraph, а не как контейнерная изоляция -- файловой изоляции на чат сейчас нет -- `/workspace` как общий mount для Matrix bot и platform-agent сейчас не настроен -- отдельного upload API для вложений в текущем коде не видно - -Ключевые файлы: -- `external/platform-agent/src/api/external.py` -- `external/platform-agent/src/agent/service.py` -- `external/platform-agent/src/agent/base.py` - -## File Handling Requirement - -Пользовательский запрос на текущем этапе: -- принимать файл или сообщение с файлом из Matrix -- сохранять файл локально -- передавать агенту явный сигнал, что к сообщению есть вложения -- сообщать, где лежит файл - -Но есть техническое ограничение: -- если Matrix bot пишет файл только в своём контейнере, platform-agent его не увидит -- значит нужен либо общий storage, либо upload в платформу, либо контейнеризация platform-agent с общим volume - -## Recommended Design Direction - -Самый прагматичный MVP-вариант: -- хранить вложения в общем каталоге, который виден и Matrix bot, и platform-agent -- формировать для агента структурированный payload с: - - локальным путём - - original filename - - mime type - - attachment type -- если есть текст пользователя, дополнять сообщение краткой summary-подсказкой про вложения -- если прислан только файл, отправлять synthetic message вроде “пользователь прислал файл” - -Если общий каталог невозможен в текущем runtime: -- следующий вариант это upload endpoint в platform-agent -- Matrix surface скачивает файл и загружает его в платформу, а платформа уже кладёт его в своё доступное хранилище - -## Open Questions - -1. Где должен жить shared storage: host path, docker volume или platform-side volume? -2. Нужен ли немедленный upload API в platform-agent, или сначала достаточно shared path? -3. Должны ли файлы быть scoped per room/platform_chat_id, а не per user? - -## Next Step For Another Agent - -1. Подтвердить runtime-модель хранения файлов. -2. Проверить, как сейчас запускаются Matrix bot и platform-agent в реальной dev-схеме. -3. После выбора storage contract начать с изменений в Matrix attachment ingestion. - -## Notes - -- Контекст этой сессии сохранён как отдельный thread, потому что текущий следующий рискованный шаг уже не про context routing, а про файловый transport. -- Не смешивать этот трек с незавершённой историей про `!branch`: upstream branch/snapshot API всё ещё не подтверждён.