docs: create thread — matrix dev prototype agent platform state

2026-04-16 12:01:26 +03:00 · 2026-04-16 12:01:26 +03:00 · 3f39b7002a
commit 3f39b7002a
parent c004d96785
1 changed files with 133 additions and 0 deletions
--- a/.planning/threads/matrix-dev-prototype-agent-platform-state.md
+++ b/.planning/threads/matrix-dev-prototype-agent-platform-state.md
@ -0,0 +1,133 @@
+# Thread: Matrix dev prototype — состояние агента и платформы
+
+## Status: OPEN
+
+## 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 для разработчиков скиллов