Brainstorm: protocol picogent<->tracker, MCP tools, WS events, prompt guidelines

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: "<event_type>", 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 (из конфига)