diff --git a/BRAINSTORM-PROTOCOL-2026-02-20.md b/BRAINSTORM-PROTOCOL-2026-02-20.md new file mode 100644 index 0000000..51921de --- /dev/null +++ b/BRAINSTORM-PROTOCOL-2026-02-20.md @@ -0,0 +1,147 @@ +# Брейншторм: Протокол Picogent ↔ Tracker +Дата: 2026-02-20 + +## Принцип + +Два слоя, чётко разделены: + +1. **WebSocket** — real-time: события (push от трекера) + сообщения чата +2. **REST (через MCP tools)** — все мутации: задачи, этапы, файлы, статусы + +Агент (LLM) не знает про WS-протокол. Он вызывает MCP tools. +Router (picogent) получает WS-события и решает: показать агенту или обработать внутренне. + +## WebSocket Protocol + +### Инфраструктура (Agent ↔ Tracker) + +``` +Agent → Tracker: + {type: "auth", token: "...", agent: {name, slug, capabilities}} + {type: "heartbeat", status: "idle|busy", current_tasks: [...]} + {type: "ack", id: "event-uuid"} + +Tracker → Agent: + {type: "auth.ok", agent_id: "uuid"} + {type: "auth.error", message: "..."} +``` + +### События (Tracker → Agent, push) + +``` +{type: "event", id: "uuid", event: "", data: {...}} +``` + +| Событие | В промпт LLM? | Описание | +|---------|---------------|----------| +| task.assigned | ✅ Да | Тебе назначена задача → начать работу | +| task.taken | ❌ Нет | Кто-то взял задачу → убрать из доступных (internal) | +| task.status_changed | ⚠️ Иногда | Только если зависимость разблокировалась | +| task.comment_added | ✅ Если mention | Новый комментарий → ответить/исправить | +| chat.message | ✅ По режиму | listen:all → всё, listen:mentions → только с @mention | +| agent.status_changed | ❌ Нет | Internal state | + +### Сообщения чата (Agent → Tracker, через WS) + +``` +Agent → Tracker: + {type: "chat.send", chat_id: "uuid", content: "текст", mentions: ["slug"]} + +Tracker → Agent: + {type: "event", event: "chat.message", data: {chat_id, author_slug, content, mentions}} +``` + +## MCP Tools (Agent → Tracker REST API) + +Все мутации — только REST. MCP tools вызывает LLM по своему усмотрению. + +### Задачи +| Tool | Method | Endpoint | Описание | +|------|--------|----------|----------| +| get_task | GET | /tasks/{id} | Получить задачу | +| list_tasks | GET | /tasks?project_id=&status=&assignee= | Список с фильтрами | +| create_task | POST | /tasks | Создать задачу/подзадачу | +| update_task | PATCH | /tasks/{id} | Обновить поля (status, priority...) | +| take_task | POST | /tasks/{id}/take | Взять себе (атомарно) | +| reject_task | POST | /tasks/{id}/reject | Отклонить с причиной | + +### Этапы (Steps) +| Tool | Method | Endpoint | Описание | +|------|--------|----------|----------| +| add_step | POST | /tasks/{id}/steps | Добавить этап | +| complete_step | PATCH | /tasks/{id}/steps/{index} | Отметить выполненным | +| list_steps | GET | /tasks/{id}/steps | Текущие этапы | + +### Комментарии +| Tool | Method | Endpoint | Описание | +|------|--------|----------|----------| +| add_comment | POST | /tasks/{id}/comments | Комментарий (с mentions) | +| list_comments | GET | /tasks/{id}/comments | Прочитать комментарии | + +### Чат (альтернатива WS, fallback) +| Tool | Method | Endpoint | Описание | +|------|--------|----------|----------| +| send_message | POST | /chats/{id}/messages | Отправить сообщение | +| read_messages | GET | /chats/{id}/messages?limit= | Прочитать историю | + +### Файлы +| Tool | Method | Endpoint | Описание | +|------|--------|----------|----------| +| upload_file | POST | /tasks/{id}/files | Прикрепить файл | +| list_files | GET | /tasks/{id}/files | Список файлов | + +## Prompt Guidelines (заметки для промпта агента) + +``` +## Работа с задачами + +- Получил задачу → прочитай описание через get_task() +- Если задача сложная → разбей на этапы через add_step() +- Обновляй этапы по мере работы через complete_step() +- Если нужно декомпозировать → создай подзадачи через create_task(parent_id=...) +- Если не можешь выполнить → отклони через reject_task() с объяснением +- После завершения → комментарий через add_comment() + update_task(status="review") + +## Коммуникация + +- Вопрос другому агенту → send_message() в чат с @mention +- Пришло сообщение с @mention → ответь +- Системные уведомления (task.taken, status changes) обрабатываются автоматически +``` + +## Архитектура в Picogent + +### Router (обработка WS-событий) +``` +WS event → Router: + task.assigned → buildPrompt() → runAgent(prompt, mcp_tools) + chat.message → если mention/listen:all → runAgent(message, mcp_tools) + task.comment → если mention → runAgent(comment, mcp_tools) + task.taken → internal: убрать из available (НЕ в промпт) + task.status → internal: проверить зависимости (НЕ в промпт) +``` + +### MCP Tools (регистрация) +``` +MCP Server → tools: + get_task, list_tasks, create_task, update_task, take_task, reject_task + add_step, complete_step, list_steps + add_comment, list_comments + send_message, read_messages + upload_file, list_files +``` + +Каждый tool = HTTP request к Tracker REST API с Bearer token. + +## Что менять + +### В Tracker: +1. WS handler: auth/auth.ok/event dispatch/ack +2. REST API: steps CRUD, reject_task, take_task (atomic) +3. Event dispatch: при assign/take/comment → WS push + +### В Picogent: +1. MCP tools provider (обёртка над TrackerClient REST) +2. Router: разделить "в промпт" vs "internal" +3. WS протокол: согласовать с трекером +4. Listen modes: all vs mentions-only (из конфига)