docs: remove legacy threads and reports from planning state
This commit is contained in:
parent
9fc0b72ab1
commit
3340c126d6
4 changed files with 0 additions and 378 deletions
|
|
@ -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
|
|
||||||
---
|
|
||||||
|
|
||||||
<current_state>
|
|
||||||
Phase 04 полностью завершена и закоммичена на ветке `feat/matrix-direct-agent-prototype` (135 тестов зелёные). Этот сеанс был посвящён архитектуре деплоя — изучили платформенные репозитории и обсудили топологию с командой платформы. Вся информация о деплое зафиксирована в `docs/deploy-architecture.md`. Phase 05 не спланирована, следующий шаг — `/gsd-plan-phase`.
|
|
||||||
</current_state>
|
|
||||||
|
|
||||||
<completed_work>
|
|
||||||
|
|
||||||
- Изучены актуальные версии platform-agent, platform-agent_api, platform-master
|
|
||||||
- Уточнена топология деплоя с платформой (схема с reverse proxy и shared volume)
|
|
||||||
- Созданы `docs/deploy-architecture.md` — полное summary архитектуры деплоя
|
|
||||||
</completed_work>
|
|
||||||
|
|
||||||
<remaining_work>
|
|
||||||
|
|
||||||
- Смержить `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` для деплоя
|
|
||||||
</remaining_work>
|
|
||||||
|
|
||||||
<decisions_made>
|
|
||||||
|
|
||||||
- **Топология**: один инстанс 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` (один контекст на пользователя)
|
|
||||||
</decisions_made>
|
|
||||||
|
|
||||||
<blockers>
|
|
||||||
|
|
||||||
- **AGENT_ID + COMPOSIO_API_KEY**: Composio смержен в main platform-agent, теперь обязателен. Значения нужны от Азамата перед деплоем.
|
|
||||||
- **agent_api #9**: убирает `attachments` и `MsgEventSendFile` — если смержат до деплоя, сломает наш file transfer. Нужно уточнить сроки.
|
|
||||||
</blockers>
|
|
||||||
|
|
||||||
## 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)
|
|
||||||
|
|
||||||
<context>
|
|
||||||
Архитектура деплоя полностью прояснена. Нет неизвестных блокеров (кроме env-переменных от платформы). Phase 05 — чисто инженерная задача: обновить конфиг, sdk, Matrix адаптер, написать compose. Всё что нужно знать — в docs/deploy-architecture.md.
|
|
||||||
</context>
|
|
||||||
|
|
||||||
<next_action>
|
|
||||||
1. /clear
|
|
||||||
2. /gsd-resume-work — прочитает этот файл и предложит план Phase 05
|
|
||||||
3. Прочитать docs/deploy-architecture.md
|
|
||||||
4. /gsd-plan-phase 05
|
|
||||||
</next_action>
|
|
||||||
|
|
@ -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`*
|
|
||||||
|
|
@ -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 для разработчиков скиллов
|
|
||||||
|
|
@ -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 всё ещё не подтверждён.
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue