From 65445f516f7c15a0e21be2608896d463ca136503 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sun, 3 May 2026 00:31:20 +0300 Subject: [PATCH 1/3] 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 2/3] 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 3/3] 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 всё ещё не подтверждён.